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Preface 


The Digital Technical Documentation Handbook describes the process of 
creating effective technical user information at Digital Equipment Corporation. 
In addition, it describes techniques for improving the usefulness of user 
information, covering such topics as creating effective indexes, maintaining 
consistent terminology, and developing usability studies. 


This handbook is intended to be used with The Digital Style Guide, a complete 
guide to style for Digital™ technical user information. 


Audience 
This handbook has two major audiences: 


¢ The technical publications community of Digital Equipment Corporation 


¢ Third-party partners of Digital, other Digital customers, and those working 
with open systems 


In addition, universities and colleges may use this material as a case study of 
the technical communication processes and techniques within a company. 


Structure of This Handbook 
The guide is divided into four parts and a glossary and index. 


¢ Part I: Environment 


— Chapter 1 describes the goals of user information and the changing 
environment of technical communication. 


e Part II: Process 


— Chapter 2 gives an overview of the stages in the information 
development process. 


— Chapter 3 describes how to gather information about the audience and 
product. 


— Chapter 4 discusses the concepts of designing modular information and 
presents a case study in designing an information set. 
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Chapter 5 gives guidelines for writing an information plan. 


Chapter 6 discusses the draft and review process and describes the 
different types of reviews. 


Chapter 7 gives an overview of the general production and delivery 
process. 


Chapter 8 describes the activities involved in closing a project and 
archiving project materials. 


Part III: Techniques 


Chapter 9 provides techniques for maintaining consistent terminology. 
Chapter 10 discusses how to create effective indexes. 


Chapter 11 describes the different ways that Digital provides 
information on line to its customers. 


Chapter 12 describes different navigational cues that increase users’ 
access to the information they need. 


Chapter 13 describes different ways to test the usability of user 
information. 


Chapter 14 describes how to research trademarks. 


Part IV: Appendixes 


Appendix A contains a series of quality control checklists that you can 
use at different stages throughout the information creation process. 


Appendix B is a selected bibliography of resources for professional 
technical communicators. 


Related Information 


The following resources also contain information about creating useful 
technical information: 


The Digital Style Guide 


Developing International User Information 


Digital Guide to Developing International Software 


NAS Guide to Documenting Multiplatform Products 


The Digital Guide to Developing Software 


See Appendix B for information on obtaining these resources and on other 
helpful references. 
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Conventions 


This guide uses the following conventions: 


Convention 


you 


italic type 


boldface type 


monospace type 
nnnnn.nnn nn 


n.nn 


OpenVMS™ systems 


Acknowledgments 


Description 


The second person refers to the information team as a 
whole, including the functions of writing, editing, graphic 
design, and production. If a specific function or person is 
meant, such as the writing function, the guide names the 
function explicitly, for example, The writer. . . 


Horizontal ellipsis points indicate the omission of material 
from an example. The information is omitted because it is 
not important to the topic being discussed. 


Vertical ellipsis points indicate the omission of information 
from an example. The information is omitted because it is 
not important to the topic being discussed. 


Italic type sets off references to terms used as or singled out 
as terms and the complete titles of manuals. In the index 
and glossary, italic type indicates cross-references to further 
information. 


Boldface type identifies terms defined in text and in the 
glossary. 


Monospace type sets off examples. 


A space character separates digits in numerals with 5 or 
more digits. For example, 10 000 equals ten thousand. 


A period in numerals signals the decimal point indicator. 
For example, 1.75 equals one and three-fourths. 


Refers to OpenVMS Alpha systems and OpenVMS VAX™ 
systems unless otherwise specified. 


Many individuals within Digital helped to develop the material in this guide, 
devoting many hours to researching, writing, and reviewing. We cannot 
possibly list everyone who contributed to the project, but we thank all of them 
for their time and expertise. We would also like to thank Fern Reiss, the initial 
project leader who coordinated the work that began this guide. Thanks also go 
to our management for letting us devote the time needed to the project. 
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Partl 


Environment 


The chapter in this part describes the user information 
environment: 


¢ Goal of user information 


e Information team members 


e Product team members 


e Changing factors in the user information environment 
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User Information Environment 


User information is any material, in printed or electronic 
form, that does one or more of the following: 


e Trains users to use a product 


¢ Describes the features of the product in a way that users 
can readily find the information they need 


e Shows users how to make the most efficient use of product features to 
complete their tasks 


¢ Provides conceptual material that helps the user understand how the 
product works with other products 


User information is composed of modules, cohesive units of information. 
Modules may be combined into larger components, such as a book, CBI, 

or a collection of related help topics. The collection of all the modules and 
components for a product is called the information set. See Section 1.4.4 and 
Chapter 4 for more information on modules. 


The product may be hardware, software, or an integrated system. It may 
also be a process, standard, or conceptual information. The task of the user 
information team is to make the product usable for the audience of the 
product, whatever it may be. See Section 1.2 for more information on the user 
information team. 


This chapter discusses the elements that make up the user information 
environment at Digital Equipment Corporation: 


¢ Goal of user information (Section 1.1) 
e Functions of the user information team (Section 1.2) 
e Product team (Section 1.3) 


e¢ Changing environment for user information (Section 1.4) 


User Information Environment 3 


1.1 Goal of User Information 


The goal of user information is to organize information in such a way that 

the users can efficiently learn the product and use the product to accomplish 
their tasks. To achieve this goal, the user information must meet the following 
criteria: 


e Accuracy 


One of the key demands for technical information is that it be accurate. 
For users to accomplish tasks safely and easily, they must have the correct 
information at hand. Inaccurate information may expose the user to 
unnecessary frustration, delays, or even danger. 


To ensure accuracy, the user information team must work with the product 
team as full partners and must also ensure that there is adequate review 
of the information. Chapter 6 provides further information about ensuring 
technical accuracy. 


¢ Appropriateness 


The information given to the users must be appropriate for their needs 
so that they are not overwhelmed by a sea of information. Chapter 4 and 
Chapter 13 provide further information on designing information to meet 
users’ needs. 


¢ Accessibility 


If users cannot find the information they need, then its accuracy and 
appropriateness are useless because the users cannot perform their tasks 
efficiently. Chapter 10 provides guidelines for creating effective indexes, 
a primary means of making information accessible to users. Chapter 12 
describes navigational cues you can use to increase users’ access to 
information. 


¢ Clarity 
To be useful, information must be written in language that is concise, clear, 


and consistent. See The Digital Style Guide for information on Digital 
style. 


¢ Completeness 


In designing and creating the user information, the user information 
team has to decide what material is necessary and sufficient for users to 
accomplish their tasks. For example, all necessary steps in a procedure 
must be documented, and all requirements for a product’s safe installation 
and use must be clearly described. 
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1.2 User Information Team 


For user information to meet its goals, the user information team must 
contain members who are responsible for writing, editing, graphics, and 
production. All the team members must be involved from the planning 

stages onward, or important considerations may be overlooked. In most large 
publications groups at Digital, different individuals are responsible for writing, 
editing, graphics, and production. However, in smaller groups, these functions 
may not be separated. For example, one individual may work as the writer and 
rely on peer reviews for editorial comments. In other groups, one individual 
may be responsible for all the functions. 


Whatever the organization of the group, the functions described in the 
following sections need to be considered in the process of planning and creating 
user information. While it may be easy to say that writers write, editors 

edit, graphic designers design, and so on, the roles are complex, and the 
specialization that each function brings to the team is important. 


1.2.1 Writing 


The writer is responsible for creating and revising the user information. The 
writer is the main contact with the technical experts. The writer is responsible 
for gathering the information contained in the project plans (see Chapter 3) 
and synthesizing that information so that the user information team can 
design the information set. Once the team designs the information set, the 
writer is responsible for creating the user information plan and having it 
reviewed (see Chapter 5). 


Because of the increasing relationships among products, the writer may also be 
responsible for working with other information teams to develop material that 
shows how several products are used together (cross-product information). 


As the project unfolds, the writer goes through the intense process of turning 
technical requirements and specifications into information that meets the 
criteria of accuracy, appropriateness, accessibility, clarity, and completeness. 
During this phase, the writer works as an interviewer, talking with the 
technical experts to clarify features and functions, the way those items 

work, and their interrelations. The writer may also work with the technical 
experts on the design of the user interface. The writer also tests the product, 
creates and tests examples, and works with the other team members to decide 
on appropriate artwork. The writer must also decide how to link related 
information (particularly important in online information). In most groups, 
the writer also creates the index entries during the writing cycle. The writing 
cycle is iterative: the writer designs the information based on the audience 
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and product research, creates the material, tests it, and revises it based on the 
testing results. 


As the information takes shape, the writer is responsible for ensuring that 
the appropriate people review the material, scheduling the reviews, and 
incorporating comments from those reviews. This process is repeated for each 
review cycle. See Chapter 6 for details on review cycles. 


As the project nears completion, the writer is also responsible for making sure 
that the information files are coded correctly for final production. The writer 
collaborates with the production group throughout the cycle to ensure that the 
files will be ready to turn into a finished product. 


The writer’s responsibilities do not end when the draft is delivered for 
production. The writer must be available to answer production questions 

that may affect the technical accuracy of the information and to handle last- 
minute technical changes. In addition, the writer works with the rest of the 
team to close the project: ensuring that files are correctly archived, that there 
is a post-production meeting if needed, and that someone is responsible for 
answering user queries about the finished user information. See Chapter 8 for 
more information on project closure. 


Writers, therefore, must bring the following expertise to the job: 


e Experience in the craft of writing and a knowledge of different methods for 
creating effective user information 


¢ Research, analysis, and interviewing skills 


¢ Technical skills, both in the products being developed and in the tools used 
to create the user information 


¢ Project and time management skills 


1.2.2 Editing 


Editors work with the team to ensure that all aspects of quality, from the 
writing style through the finished product, are considered throughout the cycle. 
Editors typically fill the following roles on the team: 


e Advisors on how to organize and present information to fit the needs of 
users, including online navigation 


e Experts on all aspects of language use, including style and word choice in 
addition to grammar, mechanics, and punctuation 


¢ User advocates, acting as first users to test the effectiveness of information 


e Experts on standards and other means of achieving consistency, including 
the development of conventions and glossaries 
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e Advisors on ensuring that information is written for an international 
audience 


e Advisors on the total process, from planning through manufacturing, with 
an understanding of the impact of various actions on the total process 


As part of the information team, the editor actively participates in planning 
the information. The editor raises questions about the appropriateness of the 
scope, organization, and methods of presenting information for the defined 
audience. In addition, the editor provides expert advice on packaging and on 
standards. The editor also contributes to the user information plan, making 
sure that it is complete and well written and that schedules and packaging 
plans are manageable and correct. 


During the review cycle, the editor works with the writer to perfect the 
information, both through informal and formal reviews. Ideally, the editor is 
able to look at drafts several times to concentrate on different levels: 


¢ Developmental editing for the organization and scope of the material 
e Substantive editing for the style, tone, and accuracy of the writing 


¢ Copy editing for the consistent and correct use of grammar, punctuation, 
mechanics, and formatting 


See Chapter 6 for further information on what editorial reviewers look for. 


During production, the editor works closely with the production group to 
ensure that the information is reproduced correctly with the proper format and 
meets the standards for finished products. See Chapter 7 and Appendix A for 
further information on production and on manufacturing standards. 


1.2.3 Graphics and Production 


Graphic designers and production specialists are the experts in graphics and 
design, text formatting, and tools. 


During the planning stages, the graphics and production experts can help 

the team decide which text and graphics tools are appropriate for the type 

of work being planned. In addition, they can work with the team to develop 
different presentation strategies, a key factor as the need for more concise and 
more graphic information increases. In addition, the graphics and production 
experts also ensure that schedules are sufficient for the type of work needed 
during production and manufacturing; they also advise the team on packaging 
and manufacturing. 
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As the project develops, graphic designers and production specialists work with 
the information team in various ways: 


¢ Selecting formats and page designs and creating new formats and designs 
when appropriate 


e Helping to decide what technical illustrations are needed and developing 
them 


e Helping to decide what other graphic elements are needed (such as posters 
or cards) and developing them 


¢ Defining symbols and icons to be used in the interface and in the user 
information 


¢ Solving problems in text formatting 
e Testing information source files for correct coding 


In addition, the graphics and production experts can also work with the 
engineering team to improve the visual impact of the user interface. 


During production, production specialists ensure that the information is 
formatted correctly and meets the quality standards for the distribution media. 
See Chapter 7 and Appendix A for further information on production and on 
manufacturing standards. 


1.2.4 Other Functions in the User Information Team 


Depending on the project scope and complexity, the user information team 
may need to consider additional areas of responsibility beyond writing, editing, 
graphic design, and production. Again, these functions may be performed by 
existing members of the information team or by other individuals. 


For large projects with multiple writers, there is often a project team leader. 
The project leader’s responsibilities may include: 


e Keeping track of all project documents and discussing changes with the 
other members of the information team. 


e Finding out about new technologies and procedures that are relevant to the 
user information effort. 


¢ Writing, revising, and obtaining approval of the information plan. The 
project leader may delegate responsibility for parts of the plan to other 
members of the information team. 


e Helping management make writing assignments based on the project needs 
and the skills and interests of the writers. 
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¢ Coordinating the overall information schedule, including review dates and 
the progress of work by the different writers. 


¢ Coordinating the reproduction and distribution of drafts for review. 
e Devising contingency plans for changes in project focus or schedule. 
e Helping writers by: 


— Clarifying technical concepts or directing the writer to the right 
resource 


— Helping to prepare work schedules 


— Explaining project goals, risks, contingencies, and user information 
needs 


e Establishing and maintaining the flow of information between the 
information team and other groups (technical team, product team, and 
so on). 


e Representing the information team at technical team or product team 
meetings. . 


e Presenting plans or status in reports and at project team meetings. 


¢ Working with related groups to coordinate schedule and cross-product 
interdependencies. 


¢ Coordinating with third-party representatives. 
e Assisting in the professional development of more junior team members. 


If the information is being localized (translated or modified for a specific 
region), someone on the information team must work with the group 
responsible for the localization. This person is usually called a translation 
coordinator. The translation coordinator’s tasks may include the following: 


e Negotiating file transfer dates 


e Ensuring that drafts of plans and the information are made available to 
the localization group representative 


e Reviewing any plans for localization and translation developed by the 
localization groups 


e Reviewing all user information to ensure compliance with applicable 
internationalization standards and guidelines 


e Ensuring that text and art source files are made available to the 
localization teams in a timely way 
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1.3 Product Team 


The user information team is part of the larger product team (sometimes 
known as the program team). This team may include representatives from the 
following functional areas: 


¢ Customer services: Provides the link between the field and engineering in 
developing solutions to customer problems 


e Engineering: Designs and develops the product 
e Manufacturing: Replicates and distributes the product to customers 


¢ Marketing: Analyzes the market and researches the product needs of 
customers 


e Product management: Organizes the product development cycle, prepares 
the business plan, and gathers product requirements 


¢ Quality assurance: Tests the product to make sure it meets established 
standards 


e Sales: Sells products and packages to customers 
e¢ Training: Develops and conducts courses for customers and employees 


¢ Usability engineering (human factors): Helps the technical team increase 
the usability of the product (hardware or software), including ergonomic 
hardware design, interface design, symbols, screens, and packaging 


For more information on the function of these groups and their responsibilities 
in the product development cycle, see The Digital Guide to Developing 
Software. 


Section 1.4 discusses the changing nature of Digital’s business, with its 
increased emphasis on open systems, multiple platforms, shorter product 
development cycles, and so on. Because of these changes, external vendors and 
customers are becoming more involved in influencing product design and in 
providing feedback on product prototypes early in the development cycle. This 
involvement may extend the concept of the product team to include external 
vendors and customers. 


1.4 Changing Environment 


This guide provides a snapshot of the current processes for developing user 
information. However, both the types of information needed and the methods 
of supplying information are changing. The following sections discuss these 
changes. 


10 User Information Environment 


1.4.1 Strategic Directions: Products, Services, and Solutions 


Digital’s strategy is to deliver distributed computing power to a variety of 
customers, large and small, worldwide. Traditionally, customers purchased 
hardware, software, and documentation — products — for one of Digital’s 
operating systems. Today, Digital supports networked computing on a variety 
of operating systems, or platforms. Digital is also developing options to protect 
and enhance customers’ investment in their purchases from Digital and from 
other computer manufacturers. These options include training, services (such 
as customized software), and solutions (large integrated systems of components 
packaged for specific business markets). 


Open architectures offer yet another opportunity for Digital to support the 
customers’ ability to integrate information management worldwide. In this 
open environment, Digital shares product information with other companies 
early in the product cycle. The supporting information consists of plans, 
architectural guidelines, functional specifications, and similar pieces that in 
the past were circulated only internally. However, this product information is 
now the major, and sometimes the only, criterion available for judging Digital’s 
technology. In addition, in an open environment, Digital must provide not only 
a user interface but also an application programming interface that lets others 
modify, build on, or even recreate the user-level characteristics of the product. 


These trends have an impact on information development: 


e The user information team must design information for multiple platforms. 
This requirement means making decisions about balancing the need for 
concise explanations for using the product against the need to handle 
platform-specific items (such as differences in terminology and syntax). For 
details on creating user information for multiple platforms, see the NAS 
Guide to Documenting Multiplatform Products and The Digital Style Guide. 


In addition, in an open environment, Digital must be ready to exchange 
information with, sell information to, or buy information from other 
vendors. Who the vendors are, or which projects have such requirements, 
is not always clear at the beginning of the project. Therefore, following 
standard source formats and style guidelines is important to enhance the 
opportunities for sharing information. 


e Open systems intended for worldwide use also require keeping current 
with different, and sometimes conflicting, international standards. While 
no individual can possibly keep up with all developments, organizations 
need to think about how to provide information in a timely and orderly 
way to the people who need it. Groups must also actively work with other 
vendors and standards bodies to influence standards and conventions. 
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¢ The open systems environment also means that Digital has the 
responsibility for providing different types of information in earlier 
stages of the product cycle. Information teams must be able to develop 
product information before the product exists. The teams must also be able 
to develop low-level information for audiences that intend to modify the 
product as well as higher level information on how to use the product. 


e The increased emphasis on providing services and solutions may also mean 
an increased demand for providing customized information packages for 
specific customers. This demand may create new revenue opportunities 
through selling the team’s expertise, but it also means understanding 
that information is a commodity, which is a change in how information 
providers think about their services and requires expanding skills for 
working with customers. In addition, because customers use a wide range 
of tools from different vendors, information providers also need to know 
about the advantages and disadvantages of a broad range of tools. 


e Writing for an international audience requires an understanding of 
different cultures and practices. The information team must design 
information that can easily be used in different countries or modified for 
different countries. See the Digital Guide to Developing International 
Software and Developing International User Information for details on 
designing international products. 


1.4.2 New Deliverables 


The line between product information and the product itself has blurred as 
advances in publishing and training technology promote the integration of 
product information into the product itself. In the past, documentation groups 
primarily created books, and training groups developed standard classroom 
(lecture/lab) training. Today, documentation and training materials consist 

of information that is integrated into the product itself or accompanies the 
product. Different types of information include: 


¢ Books of all types, available as hardcopy documents or on a CD-ROM 
(compact disc read-only memory) 


° Computer-based instruction (CBI) and other training materials 
e Online help and learn modules built into the user interface 


The entire package of online, integrated, and hardcopy documentation is called 
the information set. 
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The user information team needs to consider how much information to present 
and how to present the information. The information team must also decide 
whether the information should be presented on line or in hard copy. For 
example, should the information be presented in a book or in the online help? 
See Chapter 4 for more information on designing information sets. 


In addition, if customer training materials are needed, the user information 
team and the training team must share information to avoid redundancy and 
ensure consistency. 


1.4.3 Advances in Information Delivery 


The last ten years have seen an explosion in the availability and sophistication 
of different publishing tools. Text, art, tables of contents, and indexes are all 
routinely created and processed on line for a variety of output devices. 


In addition, there is a definite trend towards moving information from 
hardcopy books to other forms of online information. The reasons for this 
move are numerous: 


e More sophisticated systems make it possible and desirable for users to have 
information about the user interface available while they use the interface. 


e Users are aware of the number of books they receive with a product, the 
number of pages, and the cost. Some customers feel that more pages in 
an information set means the product is more complex, and, therefore, 
harder to learn and use. While it may well be that the product’s complexity 
requires extensive information, the number of physical pages may prejudice 
the customer against the product. 


¢ Information teams need to consider the cost of manufacturing hardcopy 
information, comparing it to the cost of online information and weighing 
that difference against the customers’ expectations. 


The next few years will bring significant developments in hypertext navigation, 
content-based retrieval, and libraries of information modules. (These trends 
are touched on in this guide, but, because they are still evolving, they are 

not discussed in detail.) In addition, multimedia delivery will also become 
common, and this, too, will have a great impact on the process of designing and 
developing user information. 
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1.4.4 Changing Methodologies: Modular Design 


The changing environment also affects how information is created. Customers 
need computing solutions that work across a variety of platforms and networks. 
This need means that user information, like products, must cross platforms, 
products, markets, and audiences. 


To support the need to package and repackage system pieces, engineering 
groups use modular programming techniques. Concentrating on modules helps 
them eliminate redundant code, allow incremental compiling, more easily 
revise and maintain code, and encourage an open, compatible design. 


Information groups now face similar requirements. The growing emphasis on 
customization, different delivery media, and different markets increases the 
need to package information in different ways with relative ease and efficiency. 


Modular information design is a method of creating self-contained, reusable, 
easily maintained pieces of information. By limiting the scope of a piece 

of information to a particular topic and type, information groups can 

create information that is easily reused and more accessible. In addition, 
modular information makes it easier to target specific pieces of information for 
translation and can dramatically reduce the costs of local language translation. 
(See Section 4.1 for a further definition of a module.) 


The terms module and modular documentation have, in some ways, become 
the latest jargon in technical information. However, modular information 
is not a new concept. The best writing in the industry has always been 
modular; that is, it has always been coherent, addressed a given topic, and 
been self-contained. 


Modular information offers the following advantages: 


¢ Supports the need to reuse information 


When writers think about information in terms of owning and developing a 
book, the sections and chapters they prepare are often tightly bound to the 
organization of the book itself. A modular approach emphasizes developing 
topics that users need and underscores that the topics may be appropriate 

in a number of contexts. 


_ © Emphasizes careful content development 


An effective module is the result of good analysis during the planning 
stages, specific scope, and thorough team review. If done well, it is also 
a sign of information expertise or control over the material. Writing 
professionals who are topic experts know their material. Knowledge and 
control help produce terse and self-contained information. 
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Modules are potentially more manageable than books. Writers can be 
more thorough and efficient when writing topic modules because a modular 
approach demands focus. Focus also makes topic modules easier to review 
and refine. 


Supports customizing user information 


Because the process begins with identifying a pool of topics rather than 

a book, it is relatively easy to create any number of variants (customized 
information elements) by selecting from the pool. Information teams can 
create customized elements by providing the modules needed by particular 
users. In the ideal system, customers can also change, delete, and reorder 
modules as well as add their own modules. 


Facilitates reuse and sharing of information 


Once a discrete unit of information exists, it can more easily be reused 
in many information elements: a help system, book, CBI, marketing 
document, and so on. Modules can be passed from one information set to 
another. 


Eases revision and maintenance issues 


Clear boundaries between pieces of information help writers to identify 
and group like and unlike, stable and unstable pieces of information. On 
a simpler level, when information is isolated in a specific topic module, 
revisions and updates of the topic module can be performed only once by 
the module owner. The topic owner can then notify other users of the 
module of its changed status. 


Encourages consistency across information sets 


Writing information once and then reusing it as needed reduces 
inconsistencies in terminology and presentation. Writers spend less 

time creating the same material in different words and more time refining 
the topic modules on which they are experts. 


Reduces unnecessary duplication across information sets 


A modular design approach encourages information teams to make 
conscious decisions about which pieces of information to use and how 
best to arrange them to provide context for specific users. There are 
instances when repetition is necessary and desirable. A modular approach 
ensures that decisions in favor of information reuse are logical, conscious 
design choices made in support of users. 


The new methodology also means changes in tools and the work environment: 


Information groups will need tools that give users multiple ways of 
accessing information. 
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e As teams share sources, they need to be able to perform many different 
functions on the same modules (moving, adding, copying, linking, and so 
on). 


° In such an environment, the meaning of ownership must change. 
Modularity suggests a new work etiquette for sharing information. 


Some of these issues can be handled by training and new guidelines, while 
others involve changing the way groups think about their work. 
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Part Il 


Process 


The chapters in this part discuss the following topics: 
e Overview of the information creation process 


e Audience and product research 


e Information set design 

¢ Information plans 

¢ Draft and review process 

¢ Production and distribution 


e Project closure 


2 


Overview of the Information Creation 
Process 


The process of creating user information is crucial to the 
success of the information. Having a clear and consistent 
process helps to ensure that: 


e The right people are involved in planning and decision 
making 


¢ The information is designed as part of the product and 
not as an after-thought 


¢ No steps are forgotten in the pressure to finish the project on schedule 


The information creation process is part of the overall product creation process. 
Some projects within Digital follow what is known as the Phase Review 
Process, a formal process for managing products through their life cycles. The 
Phase Review Process provides a common set of planning, measurement, and 
implementation tools to help project teams deliver products. See The Digital 
Guide to Developing Software for more information on this process. However, 
whether or not a project uses the Phase Review Process, the major stages in 
the process are the same: 


¢ Define 

e Design 
¢ Develop 
¢ Deliver 


Table 2-1 describes the general stages in the creation process and relates the 
steps to the appropriate material in this guide. For projects that follow the 
Phase Review Process, it also relates the steps to the formal phases. 
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Table 2-1 General Stages in Creation Process 
Stage Phase Information Tasks 


Define 0 Research and analyze the product and audience needs. 
Develop preliminary outlines of information, the topics 
that the user information needs to address. Begin to 
identify needed tools and resources. Develop the preliminary 
information plan. See Chapter 3 for more information on 
researching. 


Design 1 Based on more detailed project plans, develop detailed outlines 
of the user information and decide how to structure the topics 
into an information set. Write the final information plan. See 
Chapter 4 for information on designing and structuring the 
information set. See Chapter 5 for a description of the user 
information plan. 


Develop 2 Write, test, review, and modify the user information. Produce 
drafts for preliminary deliverables (such as field test 
deliverables.) See Chapter 6 for information on the draft 
and review process. 


Deliver 3 Complete the user information, verify that it meets the goals 
defined during the planning stage, and ensure that it is ready 
for manufacturing and distribution. See Chapter 7 for more 
information on production and distribution. 


4 User information is manufactured and delivered to customers. 
Close the project: perform a post-project review, archive the 
user information, and monitor feedback from customers. See 
Chapter 8 for more information on project closure. 
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Researching the Project 


An information set is part of the product, and the 

user information team must develop a strategy that is 
synchronized with the overall product strategy. But before 
you can develop your strategy, you must identify who your 
audience is and what your product does. You then use 
this analysis to decide the topics to be discussed in the 
product information; the analysis leads to the design of the 
information set, as discussed in Chapter 4. 


This chapter discusses: 


¢ What information you need about the audience and product (Section 3.1 
and Section 3.2) 


e How you can find that information (Section 3.3) 


e What to consider when submitting information to a standards body or 
consortium (Section 3.4) 


See Chapter 13 for a description of different usability studies that you may use 
to gather audience and product information. 


3.1 Analyzing the Audience 


Digital sells products to people who purchase, use, or maintain those products. 
Members of an audience use a product to accomplish similar tasks or solve 
similar problems. As Figure 3—1 shows, a product may have more than one 
audience; if so, the different audiences are interested in learning different 
things about the product and using the product in different ways. These 
different interests influence the design of the user information. 
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Figure 3-1 One Product, Multiple Audiences 


Programmers 


Database 
Administrators 


Management 


System Managers 


Analyzing the audience helps identify the users’ skills, characteristics, and 
resources. Most important, it helps identify the tasks that the users do to 
perform their jobs. Such analysis can then help you decide what topics to cover 
in the user information. 


In gathering audience information, ask the following questions: 


e For whom is the information intended? Customers? Third-party partners? 
Internal users? 


e How varied are the users’ skills? 
— What is their educational level? 
— What is their technical background? 


— What is their reading level? 
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Do they have any special requirements? 


What is the user environment? 


Where will the product be used? For example, will the product be used 
in a large office setting, small business, or academic setting? 


What are the standard job titles within the environment? This 
information helps to identify the groups of users and their skills. 
(However, job titles do vary across companies and cultures, so you must 
use this information carefully.) 


What is the frequency of turnover? This data can help you determine 
how much time users have to learn to use a product. 


What are the work flow patterns? 


What are the major work tasks? How much time is spent on tasks? 
Who is responsible for correcting errors? Maintenance? 


What are the patterns of interaction? How many users have access to 
the information? How is data passed among users? 


How do users find the information needed for new tasks? 
Where do users go for information to solve problems? 


If there is existing user information, what pieces do users find most 
useful? Are there pieces that they do not use? 


How much time can users devote to initial training? 


What is the effect of the product on the users? 


Why are they interested in using the product? What parts of the 
product are they interested in? 


Does it allow more time for other important tasks? Does it establish © 
new types of jobs? 


‘Does it create tasks that are repetitious or boring? Does it force users 


to work in isolation from each other? Does it force them to work 
together in unproductive ways? 
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3.2 Analyzing the Product 


The product is anything that needs to be documented in some way for one 
or more audiences. Products can be hardware, software, integrated systems, 
policies, standards, or services. Depending on the product, you need to 
research the following types of information: 


Product features (the essence of what the product does and the added 
features that distinguish the product from other company products or 
competing products) 


Problems the product is intended to solve 


Prerequisite knowledge, skills, or equipment users must have to use the 
product and each function 


Knowledge or skills users will have after using the product and each 
function 


Restrictions on using the product or particular functions 
Platforms the product is intended for 
Localization issues surrounding the product 


Standards with which the product must comply 


As you research the product throughout the development cycle, continue to ask 
these questions: 


What portions of the product are visible to the users? 


Is the product new? Is it an upgrade? What similar products exist at your 
company or elsewhere? What was the history of the related product in your 
company? Is there anything significant to be learned from the information 
team of that product? 


What information about the product already exists? 
What software or hardware is required for using the product? 
What types of problems is the new or upgraded product intended to solve? 


Are the product functions or tasks similar to those commonly performed 
outside the computer environment? For example, electronic mail and text 
editors are products whose tasks are familiar to anyone who sends letters 
or writes at a keyboard. The conceptual framework for such a product does 
not need extensive explanation. 


How many tasks can be performed using the product? How detailed is each 
task? Do many tasks require subtasks? 
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¢ How will the information set be distributed? (For example, will the 
information be distributed with the product kit, on a CD-ROM, in hard 
copy?) 


¢ Will the product be translated? Will it be localized for particular 
geographies? (While this may not make a difference in the content or 
presentation of the material, it may make a difference in the process.) 


For each function and feature, ask the following questions: 

e What is it supposed to do? 

¢ What is the result of using the feature? 

e What are the defaults? 

¢ What advantages are there in the feature? 

e Are there formatting or syntax rules to watch out for? 

¢ Does this feature enhance or replace an old one? 

¢ Will this feature be mentioned in more than one context? 


¢ Do other publications need to be updated because of this information? 


3.3 Gathering Information About the Audience and Product 


Section 3.1 and Section 3.2 discuss the types of information you need to gather 
about the product and the audience. The following sections discuss sources of 
product and audience information, including: 


e Using project planning documents 
e Working with technical experts 

e Attending planning meetings 

e Using the product 


e Analyzing competitive information 


3.3.1 Reading Project Planning Documents 


Most projects have a set of official planning documents developed by the 
organizations that make up the project team. The information plan developed 
by the information team (see Chapter 5) is part of the set of project documents. 
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Table 3-1 describes the project documents that may exist for any given project. 
See The Digital Guide to Developing Software for more information on these 
documents and how they fit into the product development cycle. 


Table 3-1 Project Planning Documents 


Description 


Responsible 
Document Group 
Marketing Product or 
Requirements marketing 
manager 
Business Plan Product 
manager 
Product Product 
Requirements manager 
Product Technical team 
Specification 
(Functional 
Specification) 
Design Technical team 
Documents 
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Describes the market opportunities for the 
product. Analyzes customer needs and priorities, 
international requirements, and possible trade- 
offs. Compares the product to similar products 
(from both your company and other companies). 


Gives business metrics for evaluating the 
potential of a product in comparison with other 
similar products. Reviews the product strategy, 
business viability, and required investments. 


Describes the goals, capabilities, and charac- 
teristics of the product in measurable terms. 
Describes in detail the product features that 
satisfy the market requirements and sets 
priorities for the features. Defines the technical 
requirements of the product, including methods, 
tools, processes, and metrics. 


Gives a detailed description of what the product 
is, its functions, operations, and applications, 
including the user interface. Describes the 
product goals, actions, and metrics for success 
as well as the user environment, product 
compatibility, and standards conformance. Used 
as the basis for the information and training 
plans. 


Provides a physical model of how the technical 
team will design, develop, and integrate the 
product described in the product specification. 
Describes the data flow, data structures, 
interfaces, and design criteria for the system, 
components, and modules. Specifies testing 
procedures. Primarily for the technical team. 


(continued on next page) 


Table 3—1 (Cont.) Project Planning Documents 


Responsible 
Document Group Description 
Development Technical team Describes in detail how the product will be 
Plan (Project with other developed. Describes the tasks to be completed, 
Plan) functional the resources needed, the milestones, and so 
groups on. Includes the plans from other functions, 


including user information. 


3.3.2 Working with the Technical Team 


The technical experts on the project are your main sources of information and 
can help you understand product dependencies and interrelationships. It is 
important that you establish a strong relationship with these experts from the 
beginning of the project so that you can share information and feel comfortable 
in asking questions and raising problems. 


In talking with the technical experts, try to gain a broad interpretation of the 
product and its goals. Gaining the perspective of several experts on the project 
helps you to get different viewpoints. 


Act as a user advocate, and ask the types of questions that influence the 
product design, such as: 


© Do we have to allow for compatibility with the previous version if this 
feature is implemented? 


e Why are there two different definitions of this argument? 


e Why are there six new qualifiers for the LIST OBJECT command in one 
utility but only two new qualifiers for the same command in the other 
utility? 

¢ Does this feature have any consequences that might not be obvious to the 
user? 


e Is this feature or statement consistent with others in the product? For 
example, are some syntax keywords joined with underscores while others 
are not? 


¢ How can we design the user interface to make the most of both the features 
and usability? 


If you are unsure about the answers, keep researching until you understand 
the information. If you cannot understand the material, it is likely that the 
users also will not. The project team may have to reconsider the product 
design. 


Researching the Project 27 


3.3.3 Attending Planning Meetings 


Attending planning meetings is an important way to keep informed about the 
status of the project. While each member of the information team does not 
have to attend all meetings, it is important for the team to be represented at 
all appropriate meetings. 


Formal and informal technical meetings give you information about the 
product structure and the relationship of the components. The meetings may 
also give you a better understanding of potential problems for the user and the 
opportunity to suggest ways to make the product easier to use. In addition, 
participating in such meetings helps build your credibility as a working 
member of the project team and keep information concerns in the foreground. 


There are also formal meetings (sometimes called program team meetings) of 
representatives from all the groups that contribute to the product. Because the 
user information is a part of the whole, you need to keep track of the whole 
project. The program team meetings can give you the larger perspective. 


Not only does this perspective help you design information that fits 
intelligently with the product, but it also helps you understand where problems 
may arise during the development cycle. Unresolved problems tend to appear 
again at later points in the cycle; if you are not aware of them, you may be 
caught by surprise without a contingency plan. 


In addition, you can use these meetings to build working relationships with 
representatives from marketing, sales, customer support, training, field 
engineering, and manufacturing. These individuals contribute different ideas 
and expertise to the project, and you can use their knowledge to broaden your 
view of the product and the audience. Working with the representatives from 
the different groups also helps to ensure that your plans do not conflict. For 
example, the documentation and training teams may need to work together to 
ensure consistency and avoid redundancy. 


3.3.4 Using the Product 


One of your most important sources of learning about the product is using the 
product. An early version or prototype is often available early in the process; 
start using it as soon as possible and continue using it throughout the product 
development cycle. The prototype may not work like the final product, but it 
can give you a sense of how the product is intended to work. 


Of course, because the product is being created, you may not have access to 
a working model. Continue to raise this as an issue affecting the accuracy 
and usability of the user information. If there is a previous version, use that 
version and continue to research the differences between the old and new 
versions. If you have access to a related product, use that product. 
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Using the product helps you present information clearly, cover all needed 
topics, and exclude unnecessary topics. Your experience in learning the product 
means that you can structure the information to help users learn more easily 
and thus be more productive sooner. 


Because products rarely work in isolation, you may also need to learn about 
more than your particular product. You should learn about the environment in 
which customers use your product and may need to learn about other products 
customers use with your product. For example, a database language may be 
embedded in a host programming language. Learning about both languages 
helps you write accurate and useful examples. 


3.3.5 Using Other Sources of Information 


Reading the project documents, interviewing the technical experts and other 
project team members, and using the product are major sources of information 
about the product and audience. However, there are other important sources of 
information that can help you complete your research: 


e Information team 


Other information teams in your own or other organizations may have 
worked on similar products. Even if they cannot help you with the 
technical details, they may be able to give you the benefit of their 
experience or lead you to other individuals or other customer or support 
materials. 


e Customer visits 


Your most important source of information about customers is direct 
contact. Visit user sites, talk to customers on the phone, visit field test 
sites and participate in field test training, and attend customer courses. 
Direct customer contact lets you find out how users use the products and 
user information they already have, how often they use it, and what they 
do not use. Chapter 13 describes techniques for obtaining feedback from 
customers. 


e Internal users 


You are in daily contact with other employees who regularly use your 
company’s products to do their jobs. Talking to them and observing them 
can give you insight into how people use products and user information. In 
addition, internal users may have used other companies’ products and can 
provide some comparison. See Chapter 13 for techniques on working with 
internal users. 
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e User groups and Special Interest Groups (SIGs) 


Your company may have a user organization whose members can be 

a valuable source of information. For example, DECUS™ is the user 
organization formed by Digital customers to represent their interests to 
the corporation and to exchange information. DECUS maintains many 
Special Interest Groups (SIGs) for different topics, such as the Artificial 
Intelligence SIG, the Data Management Systems SIG, and the Hardware 
and Micro SIG. Many SIGs publish newsletters and hold regional and 
national conferences. The SIGs generally respond enthusiastically to 
questions. Work with the engineering and product managers to contact the 
SIG most closely related to your product. 


Professional groups in your area may also have special user groups related 
to your products. 


¢ User feedback reports 


Depending on their service contracts, users may send in problem reports 
or work with a support group if they find serious problems with a product. 
(For example, Digital software users may send in Software Performance 
Reports [SPRs].) The engineering or support group forwards the problem 
reports for the user information to the appropriate user information group, 
which often keeps the reports on file. 


Many groups also include postpaid mailers at the back of each book so that 
users can comment on the book’s usefulness and accuracy. These cards are 
also kept on file. Both the problem reports and the comment cards may 
give you information about potentially troublesome areas. 


The information group may also have sent questionnaires to customers 
soliciting feedback about the user information. These are also a useful 
source of information. See Chapter 13 for information on designing 
questionnaires. 


e Service and support groups 


Representatives from service and support groups work with customers 
and can give you valuable information about the types of problems that 
hinder customers and field representatives in doing their work. They 

can also provide information about other reports or online databases that 
may contain information on how customers use our products and user 
information and the questions customers have about the products and user 
information. 
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e Trade publications 


Trade magazines and books about computers can acquaint you with the 
terminology and issues of the industry as a whole and particular markets 
or applications. 


e Corporate libraries 


Your company may maintain a corporate library, which can be an important 
source of specialized information, such as competitive literature, market 
research, trade journals, and so on. Some companies also maintain online 
libraries of marketing and competitive information. 


e Courses 


Your company may offer courses to help internal employees or customers 
learn to use its products. Such courses may range from short introductions 
to intensive technical seminars. Check to see if customer courses are open 
to employees; attending a customer course gives you the opportunity to 
talk with customers about their work and about the user information. 
Employee courses give you access to specialists and other employees 

who work directly with customers so that you can better understand 

the customers’ problems and how the specialists in the field use your 
product information. If your company does not offer its own training 
courses, you can also look for training offered by local colleges, professional 
organizations, or even some computer stores. 


e Product management 


The product manager is responsible for preparing planning documents 
that outline the product priorities, goals, market needs, and international 
requirements. The product manager also coordinates the product cycle, 
working with the multiple groups on the project team. In addition, the 
product manager works with customers and contributes to the long-range 
strategy for the product family. The product manager, therefore, can give 
you useful information about the product audience as well as a strategic 
overview of the product. 


3.3.6 Analyzing Competitive Information 


Studying the sales literature and user information for related products from 
other companies is one other source of information about your audience and 
the product environment. Looking at competitive literature has two purposes: 


e¢ It helps generate ideas. The way in which a competitor organizes and 
formats information can give you both good and bad models for your own 
information. 
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e It helps define the users’ expectations. One working definition of quality 
is the distance between what the user expects and what the product does. 
Looking at competitive literature may help to define what expectations 
users have for your type of product. 


Use the project planning documents to understand who the major competitors 
are for your product. Work with your marketing representative and your 
company’s competitive literature library to borrow copies of the user 
information. (Other members of the project team may also have copies 

that you can borrow.) 


First glance over each piece to gain an overall impression of its quality and 
how the information is organized. Then each member of the information team 
can go over one or two pieces from each set. 


In examining the literature, look for the following points: 


e Visual impact 


What is your general impression of the information’s quality and 
attractiveness? Are there elements of the layout or physical packaging 
that are particularly effective? 


e Organization 


How is the material arranged? Do the divisions separate the subject in 
useful ways or indicate topics you might not otherwise think of? Is the 
pattern of development easily recognized? Can users easily find what they 
need? What elements contribute to that ease of navigation? 


° Quality of writing 
Does the text use stylistic or syntactic techniques that can help improve 
your text? Are there problems you can avoid? What is done especially 
well? 

°¢ Graphics 
What graphics are used? How are they integrated with the text? In what 
way do they contribute to the usefulness of the text? 

e Syntax 
How are commands, statements, and so on depicted? Is the approach 


easier to understand than the one you were considering? What problems 
might the approach have? 
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3.4 Special Considerations: Submitting to a Standards 
Organization or Consortium 


If your product is part of a submission to an external standards body or 
consortium (such as the Open Software Foundation™), you need to consider 
some additional items. Determine as early as possible which components of the 
information set will be submitted. Work with the project team to understand 
the requirements and expectations. You may also need to work with your legal 
representative if there are questions about sharing confidential information. 


When considering the requirements, think about the following information: 
e Are source files as well as output files required? 

e¢ Ifsource files are required, what are the formatting constraints? 

e What graphics format is required? 

¢ What type of online information is required? 

e Is hypertext required? 

e What are the style guidelines? 


e Are there any postsubmission requirements, such as updates or 
corrections? 
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4 


Designing the User Information Set 


As the information about your product and audience becomes 
more concrete, you need to begin designing your information 
set. You are unlikely to complete the final design in one 

or two sessions. Rather, you continue refining the design 
throughout the product development process. 


Design is an iterative process. As product and audience 
requirements change, the information set design evolves both during the 
product cycle for one version and across versions. However long the cycle, the 
design process follows several steps: 


1. Design and structure the user information based on the product and 
audience research. 


2. Develop drafts of the information. In the preliminary stages, the drafts 
may be as skeletal as the topic title, the topic sentence, and an outline of 
the contents. 


3. Test the effectiveness of the design and the usability of the information 

' at various points throughout the product cycle. Such checks can identify 
problems with the overall design as well as with the information itself. 
Your testing may be as informal as soliciting review comments from 
the technical experts or as formal as customer-site visits with planned 
interviews. 


4. Refine the user information based on testing feedback. Improvements to 
the information set are continuous. You may gather more information that 
gives your a better understanding of the product or a clearer view of the 
users’ needs. There may be changes to the product as the technical experts 
refine their work or changes in your group’s methods and technology. 


This chapter discusses concepts that you can use in designing your own 
information set: 


e What a topic module is (Section 4.1) 
¢ How to identify topic modules (Section 4.2) 
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¢ Information types (Section 4.3) 
¢ Information architecture (Section 4.4) 
¢ Relationship between modules, design, and architecture (Section 4.5) 


Section 4.6 describes a case study of an evolving information set design. The 
case study follows the development of an information set through the stages 
of design, testing, and refining and shows how the information team used 
the concepts of modular information and architecture to develop the evolving 
design. 


4.1 What Is Modular Information? 


As noted in Chapter 1, today’s environment increasingly stresses the need for 
modular information. But what is modular information? 


A module is a cohesive unit of information. In its simplest form, a module is 
equivalent to a coherent section. Thus, a module is the basic building block of 
the information set. 


Modules contain different types of information: conceptual, reference, and 
task-oriented. These information types are discussed in Section 4.3. 


Modules share the following characteristics: 


e A module describes a complete task, concept, or feature. A module is 
self-contained. 


¢ The length of a module varies, but the goal is to be as brief as possible, 
especially when describing task or reference information. 


¢ Most modules include a title, a topic sentence indicating scope, and the 
topic content (such as task or reference information). Many modules also 
contain some sort of illustrative material, such as a table or figure, that 
further explains the content of the module. A module can also contain a 
list of related topics. 


¢ A module can consist of text, graphics, lists, or tables. A single module 
may contain more than one of these formats. 


e A module can contain other modules, refer to other modules, or stand 
alone. 


e A module has attributes such as a source name, outgoing and incoming 
links (cross-references), and, most important, a statement of the 
information type contained in the module. 
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¢ A module can be reused or shared by different components in different 
combinations. 


4.2 Identifying Modules 


There are many different approaches to creating modular information. Some 
methods require considerable training by third-party companies. Many 

of these companies have trademarked names and strategies for preparing 
modular information. 


Check with your supervisor and manager to learn your group’s practice 
regarding modular information. What methodology is the group using? What 
technology is available that will influence your decisions in this area? What 
training is available in your group? See Section B.2 for more information. 


Whatever methodology you use, your first step in designing modular 
information is identifying the topics needed for your product: 


e Use your research into the product and audience as the base for the list 
of topics. Some people find it useful to also hold a brainstorming session 
with key members of the project team. The purpose of the meeting is to 
identify and clarify the intended audience, the tasks users perform, and 
other necessary topics. Whatever method you use, ask the following types 
of questions: 


What does each audience need to learn or understand about the 
product? 


What are the tasks associated with each segment of the product? 


Do certain product requirements suggest particular topics? For 
example, the product requirements may state that this is a new type of 
environment and that users are not familiar with it. This requirement 
suggests that the user information needs to make the audience familiar 
with the product environment. 


¢ Continue to expand each topic with increasing detail. For example, if one 
of the general topics is “Show users how to use summary queries,” more 
detailed topics might be: 


What is a summary query? What does it do? 
How to compute a total 

How to compute an average 

How to find minimum and maximum amounts 


How to count rows 
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— How to group rows 
— How to limit groups 


Each of these topics might also suggest reference topics for the commands 
that perform the functions. 


e Continue refining the topics until you are satisfied that you have a firm 
understanding of each topic, the audience for the topic, what the audience 
already knows about the topic, and what the audience needs to learn about 
the topic. 


The more clearly defined the modules are, the easier it will be to arrange, 
rearrange, and customize the information. 


¢ Make sure that the project team members review the list of topics. You 
can do this informally (by circulating the list for review or in a meeting) or 
include the topic list in the preliminary information plan. 


4.3 Identifying Information Types 


In addition to identifying topic modules, designing your information set also 
involves identifying the types of information you are providing. Each module 
fits in one of three major categories: 


¢ Conceptual information 


Describes the product environment and gives users the context of the 
product. It may explain how different products are used together in certain 
applications. It may give an overview of product features, explain the 
components of the product, and generally describe how the components 
work together. 


e¢ Task-oriented information 


Explains how the user.can accomplish a particular task using a procedure 
or series of procedures. Task-oriented information uses many examples 
that walk users through the process; in many cases, the examples form a 
sample application that users can modify for their own applications. 


Tutorials are a specific type of task-oriented information intended for 
users unfamiliar with the product. They guide the user through a set of 
basic procedures using predesigned examples. 


e Reference information 


Provides details about particular entities, explaining how they are used, 
their parts, restrictions on their use, and other details that help the user 
make the fullest use of the product. 
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Low-level modules contain only one type of information. For example, a 
reference module should not contain conceptual information. However, you 
may combine low-level modules to form a larger module. For example, the case 
study described in Section 4.6 contains components on database design and 
definition. This information is both conceptual and task-oriented: 


¢ The conceptual information deals with high-level database design 
instruction, such as normalization. 


¢ The task-oriented information deals with the procedural, “how-to” steps for 
implementing database design. 


An information component describing database design and definition may thus 
contain both conceptual and task-oriented modules. 


4.4 Information Architecture 


An information architecture describes an information group’s vision of the 
overall structure of information and how it is used. An architecture gives 
guidelines or a set of general principles for the placement of information types 
in an information set, helping information teams to eliminate unnecessary 
redundancy and inconsistencies. 


Table 4-1 shows an example of an information architecture that organizes 
hardware information by task and information type. 


Table 4—1 Organizing Hardware Information by Task and Information Type 


Primary 
Information 
Task Grouping Type Audience Description 
Hardware Conceptual Managers and company Gives information that helps 
concepts officers responsible customers evaluate the 
for planning and hardware for its suitability to 
buying equipment. the customers’ needs. 


All users who will need 
to introduce the new 
product or use the 
product in the future. 


(continued on next page) 
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Table 4—1 (Cont.) Organizing Hardware Information by Task and Information Type 


Task Grouping 


Site preparation 


Installation 


Operations 


Servicing 


Programming 


Technical 


Proprietary 
technical 


Illustrated parts 
breakdown 


Primary 
Information — 


Type 


Reference, 
task-oriented 


Task-oriented 


Conceptual, 
reference, task- 
oriented 


Task-oriented 


Reference, 
task-oriented 


Conceptual, 
reference, task- 
oriented 


Conceptual, 
reference, task- 
oriented 


Reference 
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Audience 


Customers and service 
personnel who select 


sites and plan hardware 


installations. 


Customers and service 
personnel. 


All users. 


Customers and service 
personnel. 


General users and 
programmers. 


Programmers and 
service personnel. 


Digital service 
personnel. 


Digital service personnel 


and customers. 


Description 


Describes and explains the 
procedures for planning 

and for preparing a site 

for the product. Gives the 
specifications for items such 
as temperature and humidity 
tolerances, space, cabling, 
electricity, and so on. 


Describes the product and 
its parts and explains the 
procedures for installing the 
product. 


Describes the product 
components and functions, 
explains the procedures for 
different operations, and 
explains maintenance and 
troubleshooting procedures. 


Explains the procedures for 
service and maintenance. 


Gives tutorial information 
for general users who want 
to make the most use of the 
product features. Also gives 
reference information for 
experienced programmers 
writing code to incorporate 
the product within a system. 


Describes the technical 
details of the physical device, 
data flows, testing, error 
handling, and so on. 


Describes the proprietary 
technical details of the 
product needed for support. 


Identifies field-replaceable 
units and parts. 


Using this architecture, an information team for a complex product like a 
central processing unit might design an information set with a separate 
document for each task grouping. Another team may need to document a 
terminal and decides to combine tasks within a single component: hardware 
concepts, site preparation information, installation information, and operating 
instructions. However, the different types of tasks would be separated within 
the component. 


Figure 4-1 shows another example of an information architecture, which 
maps information types to delivery methods, suggesting that much product 
information is suited to online help. 


An architecture such as the one in Figure 4—1 does not provide all the answers 
for designing the information set; other factors also affect the design. For 
example, your target customers may have strong preferences as to what 
information you place on line and in hard copy. Similarly, the customer base 
may have hardware requirements that limit how information is presented on 
line. 


4.5 Relationship Between Methodology, Design, and 
Architecture 


Section 4.1 and Section 4.2 describe a bottom-up design process, working 

from details for a specific product. The information architectures described 

in Section 4.4 provide a top-down design, working from an overall structure, 

a general set of organizational principles. Good design addresses both the 
bottom-up and top-down approaches. As Figure 4—2 shows, the design that you 
create is your implementation of the architectural principles, your blueprint for 
building a particular information set from the product-specific topic modules. 
The information plan (described in Chapter 5) describes the design and how 
you will implement it. 
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Figure 4-1 Organizing Information by Type and Delivery Media 


Solutions 
Information 


Intellectual Materials 


Strategic information such as 5-year plans, 
architectures, and specifications that demonstrates 
Digital’s expertise. Not dependent on any particular 
product release. Helps customers write better 
applications as well as plan for the future. 


Cross—Product Work Context 


Conceptual material that helps customers 
understand what they can achieve in an integrated 
environment. Discusses the relationships between 
products but is not dependent on any particular 
product release. 


Product Work Context 


Conceptual material that describes what customers 
can achieve with the product, provides an overall 
picture of what the product can be used for, the 
principles inherent in the product. Less dependent 
on a particular release. 


Product Task Level 


Task-oriented information on how to accomplish : 
specific low-level tasks. Users access information Suited to 
as part of product. Dependent on a particular release. online help 


Product User Interface 


Context-sensitive reference information that provides 


users with help on particular items as they use product. Suited to 


online help 


Users see only the information they need at any time. 
Dependent on a particular release. 


Product 
Information 
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Figure 4-2 Building an Information Design 


Analyzing 
Data Needs 


Defining Defining 
Relations Fields 


SSS) 


Architectural 
Principles 


Tuning 


Performance 
Design 


In a standardized architecture, the information team identifies specific 
audiences and groups sets of related tasks and concepts (such as installing, 
configuring, and programming) to support the work users need to do. 


Users read information to understand concepts or perform specific tasks. 

The information team identifies topic modules and structures them in a 

way that supports the users’ goals. Modules gain meaning in the context 

of other modules or in the context of the user interface. An information 
architecture gives the structure, or context, for the modules, and the modules 
become information when they are arranged in ways that are meaningful and 
supportive of the users. 


4.6 Design Case Study: DECproduct 


This chapter uses a fictional database software product, called DECproduct, as 
a case study in information set design. 


DECproduct is a new (Version 1.0) relational database product. DECproduct 
can be used with other Digital products, such as transaction processing 
software, to help users build complex information management applications. 


DECproduct has the following characteristics and features: 
¢ Two command line interfaces: 


— The SQL language interface implements the latest ANSI standard 
language. This language lets users create and alter the database; 
insert, update, and delete data; and execute queries that select data 
from the database. 
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The database management language is a proprietary language. This 
language lets users perform backups of the database, maintain security 
in their system, configure their database across the network, and 
monitor and improve system performance. 


¢ Two DECwindows™ interfaces: 


The DECwindows interface for SQL is a graphic implementation of the 
latest ANSI standard language. 


‘The DECwindows interface for database management is a menu-based 


implementation of the command line management language. 


¢ Two platforms, ULTRIX™ and OpenVMS systems 


The DECproduct audience consists of highly-trained programmers, database 
administrators (DBAs), and system managers who have considerable 
experience with database products. 


Purchasers will generally fit in one of two categories: 


¢ Independent software vendors (ISVs) who will write and market their own 
applications layered on DECproduct 


¢ Large corporations or government institutions who will write applications 
layered on DECproduct 


DECproduct itself will not be used as a query tool by naive users. The ISVs 
and corporations write the applications that naive users see. 


The programmers, DBAs, and system managers use DECproduct to: 


°¢ Design a database 


e Create a database 


e Insert data 
e Select data 
e Update data 


e Generate reports 


e Maintain a secure environment 


e Manage the database system 


The following sections discuss steps that the DECproduct information team 
took when designing their information set. 
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4.6.1 Analyzing and Planning DECproduct 


The DECproduct information team began by analyzing the general product 
information described in Section 4.6. They read all the plans and specifications 
generated by the members of the product team. 


The team decided to use a topic/audience matrix to help them organize the 
information they had gathered. A topic/audience matrix is a grid that 
maps topics to be discussed to the users of those topics. (The concept of the 
matrix was developed by Edmond H. Weiss. See Section B.2 for bibliographic 
information.) The matrix is a technique that makes explicit what people often 
do implicitly as they plan an information set. In essence, you develop a series 
of progressively more detailed matrixes; the end result is the list of information 
modules for the product. 


Section 4.6.1.1 describes how the team produced a general topic/audience 
matrix. Section 4.6.1.2 describes how the team refined the matrix so it was 
more finely detailed. 


4.6.1.1 Developing a General Topic/Audience Matrix 
The DECproduct information team created a topic/audience matrix to help 
them analyze and plan their information set. They used the following process 
to create their first grid: 
1. Create a two-dimensional grid. Put the target audiences at the top of the 
grid. 
On the side of the grid, list the topics to be covered. 


If a particular audience segment needs to understand a topic, mark the box 
that links the user and the topic. 


4. Examine the grid. 


e Are there any topics that had no boxes marked? If so, do not include 
that topic in the information set. 


e Are there any audiences that have no boxes marked? If so, analyze 
whether the matrix was correct. If it is, then you do not need to 
address that particular audience when you design and write the user 
information. 


Table 4—2 shows the general topic/audience matrix the information team 
created for DECproduct. 
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Table 4-2 General Topic/Audience Matrix for DECproduct 


Topics 

Why buy DECproduct? 
System components 

Install DECproduct 
Maintain DECproduct 
Configure physical system 
Define database requirements 
Define security requirements 
Create database 

Maintain database 

Store data in database 
Access data in database 
Manipulate data in database 


Use query language 


Understand extensions to query 


language 


Integrate DECproduct with other 


Digital products 


System 
Manager 


mr PS PS 


xX 


Database 


a og eo 


a 


4.6.1.2 Developing a Detailed Topic/Audience Matrix 
After the team identified the overall product topic/audience matrix, they 
expanded each general topic to include more detail. They again checked which 
audience segments needed to understand which topics. Table 4—3 shows the 
detailed grid for the topic “Create database” in Table 4-2. Table 4—4 shows the 


detailed grid for the topic “Maintain database system.” 
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Application 
Administrator Programmer 


X 


MP PS POS 


Management 
(MIS 

Mor, 

Dept 

Mgr, ...) 


X 
X 


Table 4—3 Detailed Topic/Audience Matrix: Creating a DECproduct Database 


Management 
(MIS 
Mgr, 
System Database Application Dept 

Topics Manager Administrator Programmer Mgr, ..-) 

Analyze data needs x 

Analyze data dependencies xX 

Set up logical database design x 

Set up physical database design X x 

Define database with query X 

language 

Define relations, fields, and so on ».« Xx 

with query language 

Set up database security with X X 


query language 


Table 4—4 Detailed Topic/Audience Matrix: Maintaining a DECproduct Database 


Management 
(MIS 
Mgr, 
System Database Application Dept 

Topics Manager Administrator Programmer Mgr, ...) 

Configure database system xX xX 

Set up system security Xx Xx 

Run performance reports Xx x 

Tune performance X Xx 

Run backups ».4 X? 

Recover database ».4 


The team continued to refine each topic/audience matrix, adding topics and 
audiences as needed, until they were satisfied that they had an exhaustive list 
of topics. 
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As the team broke down each topic and task, they asked the following 
questions: 


What will users be able to do with the information? Do they need it to 
understand a concept? To perform a task? To understand the format of a 
statement? (See Section 4.3 for more information on information types.) 


How much do users already know about the topic? How much detail is 
needed? 


Are there multiple ways of performing the same task? Which is the 
preferred method and why? 


Do the topics have logical groupings and links to other topics? For example, 
the tasks identified in Table 4—3 form a logical grouping of similar tasks 
performed by the same audiences. There may be links between the system 
security topic in Table 4—4 and the database security topic in Table 4-3. 
There may also be links between those topics and the related reference 
information that describes the statements used to set up system and 
database security. 


4.6.2 Designing the DECproduct Information Set 


Knowing the tasks, the types of information, and the different audiences for 
that information, the team then began to design the information set. They 
began by grouping the information according to information types and using 


the 


architecture described in Table 4—5. 


Table 4—5 Organizing Software Information by Task and Information Type 


Information Type Task Grouping Audience Description 
Conceptual, task- Cross-product All users Describes components of different 
oriented products and how they are used 


Task-oriented 
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together to create applications. 
Often includes extended examples 
that users can customize for their 
own applications. 


Tutorial, New users Explains selected operations for 
beginner’s users new to the product. 

guide, getting 

started 


(continued on next page) 
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Table 4—5 (Cont.) Organizing Software Information by Task and Information Type 


Information Type 


Conceptual, 
task-oriented 


Task-oriented 


Task-oriented 


Conceptual, 
reference, 
task-oriented 


Reference, 
task-oriented 


Reference, 
task-oriented 


Conceptual, 
reference, 
task-oriented 


Conceptual, 
reference, 
task-oriented 


Task Grouping 


User 


Preinstallation 


Installation 


System 
operations 


Language 


Utilities and 
services 


Application 
programming 


Release notes 


Audience 


All users 


System operators 


System operators 


System managers 


and operators 


All users, 
but primarily 
programmers 


Programmers 


Applications 
programmers 


All users 


Description 


Describes how to use product 
efficiently. Describes procedures 
and capabilities, often moving from 
simple to complex. 


Includes information that system 
operators need to know before 
beginning an installation. May also 
include last-minute information 
that develops after the Installation 
Guide and Release Notes enter 
production. Usually is contained in 
a letter packaged with the software, 
not the information set. 


Describes, usually step by step, how 
to install the product and verify the 
installation. 


Describes the concepts and 
procedures for setting up and 
shutting down systems, system 
recovery, daily maintenance, system 
security, system performance and 
tuning, and so on. 


Describes the structure and 
capabilities of a language. 


Describes the use of utilities, 
services, and routines. 


Describes how to use the product to 
design and customize applications. 


Describes new and changed 
features, errors fixed, and known 
problems and restrictions. 


The architecture summarized in Table 4-5 does not specify how information is 
delivered. For example, reference information may be in a reference manual 
and online help; reference information on commands may be summarized in 
a reference card, or the structure of an application menu may be shown on a 


poster. 
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After organizing the information by task and information type, the group 
organized the information into a series of hardcopy books as described in 
Table 4—6. Note that this is a more traditional approach to designing a 
documentation set in that it does not take advantage of the opportunity to 
place more material on line. 


Table 4-6 Case Study: Hardcopy Information Set Design 


Book 


Introduction to 
Application Development 


Introduction to 
DECproduct 


Guide to Database 
Management and 
Performance 


System Management 
Reference Manual 


Guide to Database 
Design and Definition 


Guide to Programming 


Description 


Conceptual description of using DECproduct, transaction 
processing software, and other products to design 
applications. 


Conceptual description of the product and its parts, how it 
differs from other similar products. 


Task-oriented description of managing the DECproduct 
system, including: 
¢ Configuring and securing the system 


¢ Monitoring and tuning the system 


¢ Recovering the system 


Reference guide to all the system management commands, 
arranged alphabetically. 


Task-oriented description of designing and creating a 
DECproduct database, including: 


e Analyzing data needs 

¢ Creating the logical and physical designs 
e Creating the database 

¢ Setting up database security 


Also includes some conceptual topics to give context for 
the work, such as system security or designing for better 
performance. 


Task-oriented description of the query language, moving 
from basic tasks (accessing and storing data) to more 
complex tasks (creating databases, defining tables, and 
so on). 


(continued on next page) 
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Table 4-6 (Cont.) Case Study: Hardcopy Information Set Design 


Book 


Description 


Guide to Query 
Language User and 
Programming Interfaces 


Language Reference 
Manual 


Before Installing 
DECproduct 


Installation Guide 


Release Notes 


Task-oriented description of how to use the three interfaces 
to the query language: interactive (including command line 
and DECwindows), module language, and precompiler. 


A reference to the components of the query language. 
Begins with a table grouping the statements functionally. 
The major portion of the book is an alphabetical reference 
providing the details on the syntax, semantics, and usage of 
each language element and statement. 


Conceptual and task-oriented information the customer 
needs before installing DECproduct. Needed if there are 
last-minute changes that affect installation but cannot be 
included in the Release Notes because of timing. Ships with 
the software media. 


Task-oriented description of installing DECproduct, running 
the installation verification procedure (IVP), and installing 
and running the sample database. Ships with the software 
media. 


Description of new features, known problems and 
workarounds, restrictions, errata, information that could 
not be included in the information set because of timing. 
Available as an ASCII file on the product kit; customers can 
print before beginning installation. 


The information team recognized that their product would operate on two 
platforms. This introduced two problem areas: 


¢ How to document multiple platforms 


The team addressed how to document multiple platforms by analyzing 
each component of the information set to determine what percentage of the 
information would be platform specific. They next checked to see whether 
that information was intertwined with other material or if it was relatively 
isolated. The team concluded that the platform-specific information in all 
the components was isolated and comprised only 5 to 10 percent of each 


component. 


Because the material was so isolated and comprised such a small 
percentage of each component, the team decided that creating duplicate 
components for each platform would be unwarranted. Instead, each 
component would contain the information for both platforms. The team 
would accomplish this by preparing platform-specific information in 
separate modules. Each component would include the modules for both © 
platforms, with the modules presented in succession. For example, the 
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query language reference manual would contain a module describing 
ULTRIX file names followed by another module describing OpenVMS file 
names. 


e What information to include in ULTRIX reference pages 


The team addressed the issue of ULTRIX reference pages by analyzing 
what information they would produce on line. DECproduct needed online 
help for: 


— Each statement in the query language 
— Each command in the system management language 


— Each interface to DECproduct: interactive, module processor, and 
precompiler The team then analyzed which of these help topics were 
appropriate for reference pages. They determined ULTRIX reference 
pages were necessary for each of the interfaces. The team decided to 
use the modules in the Guide to DECproduct User and Programming 
Interfaces as the source for these reference pages. 


The team determined that the help for the query language and the 
system management language would be invoked after users had invoked 
DECproduct. Thus, reference pages would not be appropriate or required 
for those help items. 


DECproduct included an implementation of an ANSI-standard language. 
The team realized their information set might have to meet certain criteria 
for standards submission. The team knew they must determine as early as 
possible which components would have to meet standards and what those 
standards were. 


The team consulted their product team to obtain all available information 
about the standard before writing their information set. The information 
team learned that the information set must identify which parts of the 

query language were standard and which parts were Digital extensions. The 
DECproduct information team contacted other information teams who had also 
dealt with similar standards. Based on the experience of the other teams, the 
DECproduct team decided to indicate extensions to the standard in the query 
language reference manual, using color to mark the extensions in the hardcopy 
manual and using screening to mark extensions in the Bookreader™ version. 
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4.6.3 Implementing the DECproduct Information Set 


The DECproduct team began preparing their information set as described in 
Table 4—6. They prepared their documentation in a modular format, realizing 
that some material might be shared between various sources. The team paid 
particular attention to preparing the reference manuals in modules, knowing 
that this material would be their source of online help. 


4.6.4 Testing and Evaluating the DECproduct Information Set 


The information team designed and implemented various usability studies for 
their information set. 


For example, several reviewers expressed concern that the data definition and 
data manipulation statements were combined into one chapter, alphabetically 
arranged, in the language reference manual. The reviewers preferred that 
the statements be presented as two chapters. The first chapter would contain 
statements used to define data, while the second chapter would contain 
statements used to manipulate existing data. The reviewers suggested 

the statements within each of those two chapters could then be arranged 
alphabetically. 


The information team produced copies of the manual with both organizational 
schemes: one version had the statements in one chapter; the other version 
divided the statements into two chapters. 


Before field test, the team identified a group of Digital employees who were 
users of an earlier implementation of the same database language. (They 
thus had a familiarity with the product similar to that of the target audience.) 
The team devised read and locate tests for both versions of the manual. The 
purpose of the tests was to determine whether participants could find the 
statements or whether the information was buried. 


The read and locate tests determined that participants took longer to find 
statements in the two-chapter version of the manual. Several participants 
stated that they did not make the distinction between data definition and 
data manipulation statements. Based on these results, the information team 
decided to produce the statements in one chapter, not two. 


See Chapter 13 for further information on usability testing. 
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4.6.5 Refining the DECproduct Information Set 


Following field test, the DECproduct team once again examined its product and 
audience information. They decided that they needed to reduce the number 

of hardcopy components. They chose to use a newly-available architectural 
model, shown in Figure 4—1, to help decide how to present information. 


From their research, the team knew that the majority of their users did not 
have workstations to view Bookreader online books, nor would they have such 
a capability in the next 2 years. This limited the practicality of providing 
books only on line. However, the team reduced the number of hardcopy books 
by providing the reference-oriented language information in the following 
formats: . 


e Online help 


Help was available as OpenVMS help for character-cell terminals and 
DECwindows help for workstations. The help contained the details about 
the query language statements and system management commands. 


e Bookreader books 


The Guide to Database Management and Performance summarized the 
system management commands and directed users to the online help. 
Similarly, the Guide to Database Design and Definition summarized the 
query language commands and directed the users to the detailed online 
help. Both guides would be available in hard copy and on line. 


The group revised its information set design, as shown in Table 4—7. 


Table 4-7 Case Study: Modified Information Set Design 


Delivery 
Media Component Description 
Hardcopy Introduction to Conceptual description of using DECproduct, 
Application Development transaction processing software, and other 
products to design applications. 
Hardcopy Introduction to Conceptual description of the product and 
DECproduct its parts, how it differs from other similar 
products. 


(continued on next page) 
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Table 4—7 (Cont.) Case Study: Modified Information Set Design 


Delivery 
Media 


Component 


Description 


Hardcopy, 
Bookreader 


Online help 


Hardcopy, 
Bookreader 


Hardcopy, 
Bookreader 


Guide to Database 
Management and 
Performance 


System management 
reference 


Guide to Database 
Design and Definition 


Guide to Programming 


Task-oriented description of managing the 
DECproduct system, including: 


¢ Configuring and securing the system 
¢ Monitoring and tuning the system 
e Recovering the system 


Also includes a brief summary of all system 
management commands, with a reference to 
the detailed online help. 


All system management commands are 
available in online form. 


Task-oriented description of designing and 
creating a DECproduct database, including: 


e Analyzing data needs 


¢ Creating the logical and physical 
designs 


e Creating the database 
e Setting up database security 


Also includes a summary of the query 
language statements, arranged functionally, 
with a reference to the detailed reference 
information contained in online help. 


Task-oriented description of the query 
language, moving from basic tasks 
(accessing and storing data) to more 
complex tasks (creating databases, defining 
tables, and so on). Also contains a summary 
of the query language statements, arranged 
functionally, with a reference to the detailed 
reference information contained in online 
help. 


(continued on next page) 
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Table 4-7 (Cont.) Case Study: Modified Information Set Design 


Delivery 
Media 


Component 


Description 


Hardcopy, 
Bookreader 


Online help, 
product 
interface 


Online help 


Hardcopy 


Hardcopy 


Online book 


Guide to Query 
Language User and 
Programming Interfaces 


DECwindows interactive 
interface 


Query language 
reference 


Before Installing 
DECproduct 


Installation Guide 


Release Notes 


Task-oriented description of how to use 
the three interfaces to the query language: 
interactive (command line only), module 
language, and precompiler. 


Task-oriented description of how to use the 
DECwindows interactive interface. 


(To consolidate information, the team 
designated one writer to assist with the 
user interface design; the writer’s goal was 
to help create a design that would be largely 
self-explanatory.) 


All query language statements are described 
in detail in online form. 


Task-oriented information the customer 
needs before installing DECproduct. 
Needed if there are last-minute changes 
that affect installation but cannot be 
included in the Release Notes because of 
timing. Ships with the software media. 


Task-oriented description of installing 
DECproduct, running the installation 
verification procedure (IVP), and installing 
and running the sample database. Ships 
with the software media. 


Reference and task-oriented description 
of new features, known problems and 
workarounds, restrictions, errata, 
information that could not be included 
in the information set because of timing. 
Available as an ASCII file on the product 
kit; customers can print before beginning 
installation. 


56 Designing the User Information Set 


4.6.6 Further Refining the DECproduct Information Set 


At the end of the project, the information team brainstormed about how they 
might design their information for future releases. While the information 
content would be similar to what was available in the previous release, the 
format and structure would be quite different. 


The only books that would remain in hardcopy are the: 
¢ DECproduct Installation Guide 

¢ Introduction to DECproduct 

¢ Introduction to Application Development 


Because the Installation Guide is used before the product is installed, users 
must have a hard copy. The Introduction to DECproduct and the Introduction 
to Application Development are both conceptual in nature and would be used 
as marketing tools as well as part of the product information. As such, they 
are suitable for hardcopy delivery but would also be available as online books. 


The information team decided that all remaining information would be written 
in modules and would be available on line. The team agreed that technology 
would have to allow users to print out modules in any combination they chose. 
If users could not print out modules, this approach would be a burden on the 
users. 


The information team considered the following factors when deciding how 
users might access online help: 


¢ DECproduct contains two languages: the query language (SQL) and the 
system management language. 


e Each of these languages has two interactive interfaces: DECwindows and 
command line. 


Thus, online help would be accessible from any of these four configurations: 
¢ SQL, command line 

¢ SQL, DECwindows 

e System management, command line 

¢ System management, DECwindows 


The information team decided to add a new statement to the query and system 
management languages. Before invoking Help at either language prompt, 
users could enter a Set Help Reference statement to choose all reference- 
oriented help. Likewise, users could choose all task-oriented help by entering 
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Set Help Task_Oriented. The DECwindows interfaces would have the same 
feature. 


Users would see one of three combinations of module displays when they 
accessed online help: 


¢ Ifusers set their help to Reference, they would see two categories of choices 
upon invoking help: 


— Getting Started 


— A listing of the DECproduct statements 


The Getting Started module would give an overview of DECproduct and 
describe how to navigate through the various formats of online information. 


If the users chose a DECproduct statement, they would receive online help 
including a description of the statement, complete syntax, and a description 
of the arguments, usage notes, and examples. 


¢ Ifusers set their help to Task_Oriented, they would see two categories of 
choices upon invoking help: 


— Getting Started 
— A listing of task-oriented DECproduct topics, such as the following: 
* Designing a database 
* Creating a database 
* Inserting data 
* Selecting data 
* Updating data 
* Generating reports 
* Designing for security 
* Maintaining security 


* Managing the database system 
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e If users specified neither Set Help Reference nor Set Help Task_Oriented, 
they would see these choices upon invoking help: 


— Getting Started 


— Reference-oriented topics 
Upon choosing this topic, users would see the listing of DECproduct 
statements. The introductory material would also mention the Set 
Help statement so users could choose a default help designation for 
that session. 


— Task-oriented topics 
Upon choosing this topic, users would see the listing of task-oriented 
DECproduct topics. The introductory material would also mention the 
Set Help statement so users could choose a default help designation for 
that session. 


Links would also let users move from one module to related modules. For 
example, the users who were reading tutorial information on designing a 
database would easily be able to navigate to the reference material on specific 
data definition statements. 
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2 


Developing the Information Plan 


After you research the audience and product and design the 
information set, you must write an information plan (also 
known as a documentation plan). The final information 
plan is an agreement, confirmed in writing, between the 
funding group and the information group about how the 
product will be documented. The plan is not just a nicety; 
rather, it is one of the formal project planning documents 
that other groups depend on and that you use throughout the information 
creation process. See Section A.2 for a quality control checklist for information 
plans. 


This chapter describes the process of creating an information plan as well as 
the parts of the plan. 


¢ Section 5.1 describes the purpose of the information plan. 


¢ Section 5.2 compares master information plans to component information 
plans. 


e Section 5.3 describes who is responsible for writing the information plan. 
e Section 5.4 describes when to write the information plan. 


e Section 5.5 discusses scheduling, staffing, and budgeting information that 
you may need before you write the information plan. 


e Section 5.6 gives details about the contents of the information plan. 


e Section 5.7 gives details about the contents of the production and 
packaging plan, which may be part of the information plan or a separate 
planning document. 


Some of the sections in this chapter discuss the information plan in the context 
of the formal Phase Review Process used by some groups within Digital. See 
Chapter 2 and The Digital Guide to Developing Software for a description 

of that process and the requirements for each phase. However, even if your 
product does not follow the same formal process, the information is still valid. 
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5.1 Purpose of the Information Plan 
The information plan: 


e Identifies the scope of the information project, including goals, nongoals, 
the relationship to other projects, and risks and contingencies 


¢ Identifies the proposed contents of the information set 
¢ Identifies the staffing and resources needed to complete the project 


¢ Specifies the plans for production, printing, packaging, and localization, as 
applicable, as well as the tools to be used 


¢ Provides information to groups with a vested interest in the product, such 
as manufacturing, internationalization groups, and others 


5.2 Master Plans and Component Plans 


Because of the size of their projects, some groups create master information 
plans in addition to plans for each component in the information set. This is 
common, for example, for major releases of an operating system. 


The master information plan contains planning material common to the 
project as a whole, such as overall project goals or a list of staffing for all the 
components of the project. The component information plans then give 
planning information specific to each component, such as outlines, reviewers 
for a particular component, and so on. In some cases, the master plan lists the 
critical project dates (for both the technical and information group) while the 
component plans list only the information milestones for that component. 


Where needed, the sections in this chapter describe differences between master 
plans and component plans. However, your project needs determine how you 
distribute the information between a master plan and component plans. 


5.3 Who Writes the Information Plan? 


Creating the information plan is a group process and requires input from all 
members of the information team. On large projects, the information team 
project leader may be responsible for coordinating the plan. The project leader 
may write the plan with input from the group members or may delegate 
portions to different group members. If there are master and component 
plans, the project leader may be responsible for writing the master plan while 
the writers for each component write the component plans. On single-writer 
projects, the writer and writing supervisor may be responsible for coordinating 
the plan, again with help from the other team members. 
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5.4 When to Write the Information Plan 


Your group’s practices determine exactly when the information plan must be 
approved. Section 5.4.1 discusses the requirements of the formal Phase Review 
Process. Projects that do not follow the Phase Review Process have other 
requirements; for example, the information plan may need to be approved 
before any testing by external customers. 


Whatever the scheduling requirements, the information plan goes through 
several drafts and reviews. The earliest version is sometimes no more than 
a statement of the approach the team intends to take and a list of the 
information needed from other groups. (The draft plan is often called the 
preliminary information plan.) 


Circulate the draft plan among the members of the information team to 
ensure that all team members agree in general with its content. Team 
members may add issues to be raised during the formal review or may be 
able to supply answers to questions. 


As you gather more information from the project planning documents and 
other resources, you change and expand the plan. 


Send the revised plan to the members of the product team for at least 
one formal review. Send mail to the product team members notifying 
them when you will send the information plan for review and when 
comments are due. If possible, provide hard copies of the plan for the 
signoff reviewers. Otherwise, provide the file location of the information 
plan or, if the file is short, send it through electronic mail. 


If there are many issues, you may need to have several reviews of the plan, 
particularly by the signoff reviewers. (If possible, mark all changes so that 
key reviewers can easily see the changed material without rereading the 
whole plan.) 


When the plan is complete, get the written approval of the plan from your 
key reviewers. Signoff indicates that the individuals responsible for the 


project agree that the information strategy is valid and contributes to the 


quality of the product. The number of reviewers with signoff authority 
varies with the complexity and type of project. See Section 5.6.1 for the 
minimum list required. 
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5.4.1 Information Plans and the Phase Review Process 


You are not required to have a preliminary plan for the Phase 0 meeting, 
which closes the definition stage of development. However, it is better to 
have a tentative plan and a list of issues at this time. The product team thus 
has more time to evaluate your strategy, and you have clearly stated what 
problems the information team foresees so that you can spend more time on 
resolving the problems. 


After the information team reviews the plan, circulate a copy of the plan to the 
product team before the Phase 0 meeting so that everyone has had the chance 
to read the plan and prepare questions. 


At the Phase 0 meeting, you may be asked to clarify some of the material in 
the preliminary plan and report on project progress and issues. 


During Phase 1, you complete your research for the plan and answer the 
questions raised for Phase 0. (Often, the team begins working with the 
prototype product, and the writers begin writing, before the information plan 
is completed.) Send the plan out for at least one formal review during Phase 
1, and allow enough time to incorporate changes before the meeting that closes 
Phase 1. 


The information plan, along with all the other planning documents, must be 
signed off before the meeting that closes Phase 1. 


5.4.2 Changes After Signoff 


The final information plan is the information group’s commitment to deliver 
particular pieces of information by certain dates at a certain level of quality. 
However, the final plan may be modified. Changes in the project may mean 
changes to your plans. If your plans change significantly (for example, the 
group loses resources and can no longer provide one of the planned pieces 
of information), you should submit a summary of the changes to at least 
the signoff reviewers. Other groups may also need that information if they 
are depending on the material’s being available. For example, the software 
specialists would need to know that you could no longer deliver the proposed 
performance tuning information. 


If the project schedule changes, the information schedule is also affected. You 
do not have to send out a new information plan for each change. Instead, 
when the information review dates change, send a set of the new milestones 
to the reviewers listed in the information plan so that they can adjust their 
schedules. 
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5.5 Before Writing the Plan: Scheduling, Staffing, and 
Budgeting 


The information plan should include the names of the key people who are 
scheduled to work on the project, the schedule, and, for some groups, the 
budget for creating and producing the information. 


There is an interrelationship among staffing, scheduling, and budgeting. For 
all three areas, much depends on the people in your organization and the 
processes you use. Unfortunately, there are no magic formulas. 


5.5.1 Scheduling 


The beginning and end dates for a project are generally determined by the 
funder, whether you are working on an engineering project, an internal project 
for another organization, or a project for an external client. The funder knows 
when the information about the project will begin to be available to you. The 
funder also has an end date in mind. That date may be when a product needs 
to begin shipping in order to meet a certain market need. It may be the date 
when material must be provided for a certain sales event or the date when a 
customer must provide the information to another organization. 


You need to look at the critical dates in the overall project schedule and use 
those dates to determine the milestones specific to developing the information. 


For example, the critical dates for an engineering project may be the: 


e Internal product availability dates 


These milestones may be expressed as the dates when different base 
levels are available, that is, when certain product components meet a 
predefined level of usability. 


e §6Field test dates 


Field testing is a method of testing to ensure that the product meets 

its goals and works in the way the project team intends. Products may 

go through both an internal field test (IFT) by company employees and 
external field test (EFT) by selected customers. The terms Alpha test and 
Beta test are also used to refer to the concept of field testing. In addition, 
there may be field test updates, which provide field test sites with added 
product features as they are developed. These updates may also be referred 
to as FT1, FT2, ..., FTn. See Section 6.9 for more information on field 
test review. 


e Submission to manufacturing 


This date signals when the technical group submits the product to the 
manufacturing organization for replication and distribution to customers. 
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e¢ Shipment date 


This date signals the first date on which the company ships the product to 
customers. Within Digital, this date is called the First Revenue Ship (FRS) 
date. 


These are deadlines that everyone counts on: product managers, marketing, 
support specialists, and the other members of the program team. Likewise, 
corporate planning and budgeting depend on the product selling certain 
amounts by specified times. 


Your job is to look at the amount of time and determine how much work can 
be done within those limits. It may mean cutting back on the number of 
information components or staggering the amount of material available for any 
one formal review or field test. 


The computer world is neither stable nor perfect. The critical project dates 
may often change. Sometimes all the critical dates change in sequence, and 
you can move your dates accordingly. However, there are times when product 
availability or field test dates change but not the product shipment date. This 
means rethinking how much information can be delivered in the given time. 
See Section 5.6.14 for setting expectations around shifting dates. 


You need to have a firm sense of how much time is needed in your organization 
for the different steps in the process. Sometimes it is helpful to work backward 
from the end date. For example: 


* How much time is needed for manufacturing and printing? This 
time determines the date when the information must be delivered for 
manufacturing and, therefore, the date when production ends. 


¢ How much time is needed for production? This time determines the date 
when all information must be submitted to the production group and, 
therefore, when the information must be written, edited, and approved. 


¢ When is field test and how much time is needed to make copies of the 
information for field test? These times determine the date when the 
information must be sent to the copy center. The copy center deadline 
determines when the information must be ready for copying (that is, the 
material has been written and edited and meets your group’s quality 
standards for field test.) 


Include time in your schedule for the following tasks in addition to the more 
formal milestones: 


¢ Gathering information as the writer develops the draft 


¢ Writing and revising the drafts 
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e Circulating the drafts for informal technical and editorial reviews 
¢ Editing the drafts 

e Incorporating comments from technical and editorial review 

e Drafting the art and meeting with the graphic designer 

In addition, allow some time for the following: 

e Training 

e Illness and vacation 

e System downtime 

e Engineering redesign and bug fixes 

For example, you may add 1 week into the schedule for each 3 months. 
See Section 5.6.13 for suggested information plan milestones. 


Be realistic about how much work can be done in the time period given 

your group’s processes and the capabilities of your staff. As a team, discuss 
constraints and changes you must make, either to the information strategy or 
to the process. The other members of the project team expect you to commit to 
the schedule you develop in the information plan. 


5.5.2 Staffing 


As with scheduling, there are no hard and fast rules for determining the 
number of people needed on a project. You must consider the schedule, the 
complexity of the project, and the capabilities of your available staff. If your 
available staff consists of three inexperienced people, you cannot plan as if you 
had six experienced people. Also consider the following factors: 


¢ How volatile is the product? Is it likely to change many times before 
release? 


e Is the product intended for one or multiple platforms? 
e How much of the product is visible to users? 


¢ Does the technical group have a good reputation for delivering material on 
time and for working with the information team? 


Some groups use staffing ratios developed on the basis of past experience. For 
example, groups may use a ratio of five engineers to one writer, four writers 
to one editor, nine writers to one designer, and so on. These ratios can help 
you make initial projections for staffing, but you need to consider the project 
complexity and the skills of the available individuals before making the final 
decisions on staffing. 
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Another method of determining the staffing needs on a project is to determine 
the estimated page count for the ideal information strategy for the project. 
(You also need to decide the equivalence of online information to pages.) 
However, this method does not consider the fact that it takes more time to 
produce concise, nonredundant information (particularly when a group is 
revising an information set). Therefore, use the results of this method only as 
estimates. 


Based on the knowledge of your group, you have a sense of how many pages 
an individual can manage over the life of a project. (For example, you can look 
at a variety of projects that your group has worked on. Determine the total 
time of each project through final production. Divide the time by the number 
of writers on the project. Count the total number of pages for the project and 
then calculate the number of pages produced on a daily and weekly basis.) 


For example, the ideal information strategy for your new project requires 
1000 pages of new material, including online information. There are 12 weeks 
to write the user information. Based on past experience, you know that the 
individual writers in your group work at an average rate of 15 pages a week 
over the life of a project. 


15 pages/week x 12 weeks = 180 pages per person 


1000 pages/180 = 5.55 number of writers needed 


Some of the material can be written relatively easily from a template, so you 
decide to use five writers for the project. 


5.5.3 Budgeting 


Not all groups are required to include budgeting information in their plans, 
although they should understand the costs involved. 


The project budget is usually determined by the funder in some way. For 
example, the funder may determine the total number of people to be funded for 
the project, thus limiting what you can produce on the product. Or the funder 
may specify a total amount that can be spent. Given your group’s charging 
rate, you determine the amounts that can be spent for writing, editing, design, 
and production and develop an information strategy that fits within that 
budget. 


In other cases, you may be able to negotiate the budget with the funder, 
developing different strategies for different funding levels. For example, you 
may negotiate the number of components to be delivered, special graphics 
requirements, or final printing options. 
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Your project costs are determined by the following metric: 

Number of hours x number of people x hourly rate 

The hourly rate differs according to the group size and the group’s overhead 
expenses, such as charges for office space, telecommunications, or management 
and administration costs. The hourly rates used in this section are examples 
only. 

For example: 

Hourly charge rate = $50 

3 people x 50 hours each = 150 hours 

150 hours X $50 = $7500 

In other cases, you may have different hourly rates, or you may estimate that 
individuals will spend different amounts of time on the project. For example: 


Writing hourly rate = $50/hour 
Editing hourly rate = $40/hour 
Graphics hourly rate = $40/hour 


Writing Estimate 
4 writers working full-time (40 hours/week) for 4 weeks 


160 hours x 4 = 640 hours x $50/hour = $32 000.00 


Editing Estimate 
1 editor working full-time (40 hours/week) for 3 weeks 


40 x 3 = 120 hours x $40/hour = $4800.00 


Graphics Estimate 
1 designer for a total of 40 hours 


40 hours x $40/hour = $1600.00 


Total Project Budget 


$32 000.00 Writing 
$ 4 800.00 Editing 
$ 1 600.00 Graphics 


$38 400.00 Total Information Budget 


See Section 5.6.11 for a suggested format for presenting budget information in 
the information plan. 
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5.6 Information Plan Contents 


The following sections give details about the components of an information 
plan. Some groups divide the plan into two parts: Part 1, Information Content 
and Implementation and Part 2, Information Packaging. If the project is large 
and complex, as for a major release of an operating system, you may decide to 
create a separate packaging plan. See Section 5.7 for details on production and 
packaging plans. 


Each information plan should have a table of contents placed after the title 
page. Some groups also include a copyright page after the title page and before 
the table of contents. In addition, check with your legal representative about 
the appropriate use of labels marking proprietary information. For example, 
you may need to mark the plan with a label such as For Internal Use Only or 
Company Confidential. 


5.6.1 Title Page 


Figure 5-1 shows a sample title page for an information plan. The title page 
lists the signoff reviewers of the information plan. The list of signoff reviewers 
varies with the complexity and type of project. Include the following functions: 


e Editing 

e Funding organization 

e Product manager (if there is one) 

e Technical experts 

¢ Writing 

The authority of individuals to commit to the plan may differ by functional 
organization. For example, the manager of the funding organization may be 
the only individual in that group who can sign off on the information plan, 


while the supervisor of the technical group has the authority to commit to the 
plan. Check your group’s practices before creating your signoff review list. 


On some projects, the functions overlap. For example, on some engineering 
projects, the engineering group is both the funding group and the responsible 
technical group. 


The title page may also list the informational reviewers for the information 
plan. If you do not list the reviewers on the title page, include them in the 
Staffing and Reviewing section of the information plan. See Section 5.6.10 for 
details. 
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Figure 5-1 Sample Information Plan Title Page 


Digital Internal Use Only 


Date: May 13, 1991 
Discrete Project Number: 098—02168 


Final Information Plan 
DECproduct Version 1.0 


Issued by: 


DECproduct Information Project Leader -— Jacqueline Dickinson 
Node::JDICKINSON 

DTN 555-1212 

Approved by: 

Writing Manager -— Joanne Cassone 

Writing Supervisor —— Ed Perez 

Editor -— Michael Moran 


Engineering Manager —— Jason Chang 


Engineering Supervisor —— Anna Suazo 


Engineering Project Leader —— Jon Wilkes—Jones 


DECproduct Product Manager —- Frank Callahan 


Revision History: 
Preliminary draft: April 5, 1991 
Revised draft: April 30, 1991 
Digital internal Use Only 
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5.6.2 Product and Audience Overview 


Briefly describe the product, the strategic importance of the product, the 
audience, and what the product does for the intended audience. The other 
project planning documents give details about the product and audience; 
therefore, you need to give only enough information to provide context for the 
information strategy. 


If this is not a Version 1.0 release and substantial changes are involved, you 
may give a brief historical perspective of the changes, concentrating on the 
user information rather than the product itself. For example, the section 
may describe the growth of the product in the international market and the 
resulting changes necessary in the information. 


You may also give a brief audience description in this section and refer the 
readers to the Information Overview section, where you discuss the audience 
for each particular component in the information set. 


5.6.3 Relationship to Other Products 


If your product is going to be used with other products, list the other products 
here. For software products, be sure to identify the hardware on which the 
software product will run and the intended platforms. 


5.6.4 Comparison with Competition 


72 


This section evaluates the information for similar products produced by major 
competitors. Briefly describe the strengths and, if appropriate, the weaknesses 
of the competitive information. Concentrate on what is relevant to your 
information strategy. If a competitor’s information does not offer any new 
insights, then do not mention that competitor; this section is not intended for 
slighting the competition. 


Competitive information is not always available or appropriate, but this section 
is particularly useful for Version 1.0 products. It may also be useful if: 


e The product has new major competitors 
¢ Major competitors have made important changes to their information 


If your competitive analysis is extensive, you may include this material in an 
appendix to the information plan. 
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5.6.5 Information Overview 


The information overview section summarizes the information strategy, how 
you plan to describe the product in accordance with the product and audience 


5.6.5.1 


profiles. 


Information Summary 


The first part of the information overview lists each component of the 


information set: 
e The component title 


e The delivery media 


e The type of source file (indicated by the file suffix) 


e The status (new, revision, update, addendum) 


For example: 


Table 1 describes the hardcopy and online components of the DECproduct 


Version 1.0 information set. 


Source 
File Type Status 


Introduction to 
Application Development 


Bookreader 
Hardcopy 


Bookreader 
Hardcopy 


Guide to DB Management 
and Performance 


Bookreader 
Hardcopy 


Guide to DB Design 
and Definition 


Bookreader 
Hardcopy 


Bookreader 
Hardcopy 


DECproduct on ULTRI 
Installation Guide 


CONDIST 
Hardcopy 


Cl el ee lee eee rr rt rt fr rt rr ne 


DECproduct on OpenVMS 
Installation Guide 


CONDIST 
Hardcopy 


- SDML New 
SDML New 
SDML New 
SDML New 
SDML New 
SDML New 
SDML New 
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Before Installing Hardcopy ~SDML New 
DECproduct 
(letter, if needed) 


DECproduct Release Notes Kit . SDML New 

(text file on kit) 

OpenVMS Help Kit HLP New 

DECwindows Help Kit HLP New 

Reference pages Kit *roff New 
Hardcopy 


If you plan to refer to any external publications, include that information here. 
For example, some product information sets include textbooks by external 
authorities. 


In addition, if you rely on other information sets and plan to refer to them 
rather than repeating the information, include the titles, the most recent order 
numbers, and the groups responsible for the information. 


5.6.5.2 Information Set Goals 
The Goals section describes the specific objectives for the information set as a 
whole. For example, you may identify: 


e Any specific objectives about the organization, formatting techniques, and 
usability of the information in a particular market (such as objectives for 
localization) 


¢ Goals for experimenting with a particular format, organization, or approach 


Also include nongoals, those items that someone might expect you to cover 
but that you do not plan to cover, and explain why they are nongoals. 


5.6.5.3 Component Description and Outlines 


The Description and Outlines section describes each component of the 
information set. For each component, include the following information: 


e Content description, including a brief description of what is new and what 
is revised for this version. 


e Audience identification, if different components are targeted towards 
different audiences. 


e Special characteristics or unusual requirements, if any, such as a particular 
format or organization. If you already discussed this under the Information 
Set Goals, do not repeat the information here. 
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You may include an outline of the major topics for each component in this 
section. However, your signoff reviewers in particular need to see a detailed 
outline of each component to judge the organization of the information set. You 
may include detailed outlines for each component in an appendix instead of 
presenting them in this section. 


5.6.6 Online Information 


Information is being placed on line in various forms more frequently than in 
the past. Your reviewers need to know what type of online information you are 
planning. For example, the engineering group may need to plan for space on 
the kit, while the production and internationalization groups need to ensure 
that the right tools are available. 


Table 5-1 describes the information you need to include in your information 
plan for the various types of online information. See Chapter 11 for 
information on creating online information. 


Table 5—1 Planning for Online Information 

Information Type Include in Information Plan 

Online book (Bookreader) e Whether or not the information will be produced in hard 
copy as well as on line. 


e The tools you are using to produce the online information, 
including the artwork. 


e The format (doctype, macro package, style) you are using 
to produce the online information. 


Online help e Whether or not the help text is already available (for 
example, in a reference manual). If it is not, indicate 
that new information will be written for the help topics. 


e_ =A list of the application’s objects (for example, icons, 
menu items, and dialog boxes) for which help will be 
available. This information may not be available at the 
preliminary plan stage, but include as much information 
as possible. 


e An outline of the task-oriented topics. 


Online examples e_ =6A list of the extended programming examples to be put 
on line. 


e The estimated block size, if available. 


(continued on next page) 
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Table 5—1 (Cont.) Planning for Online Information 
Information Type Include in Information Plan 
Reference pages e Whether or not the references pages are updates of 
existing reference pages. 
e Page-naming conventions. 


e Nonstandard sections that you will create. 


5.6.7 File Naming Conventions 


Include the conventions you will use for naming files. The consistent use of 
clearly defined conventions makes file maintenance easier. Arbitrary file names 
can cause confusion and extra work. 


Developing International User Information recommends using the following 
convention: 


book_subject_element.file suffix 
¢ book is a unique character string that identifies the book name. 


¢ subject is a unique character string that identifies the subject of the chapter 
or part. 


¢ element identifies the type of text element, such as fig for a figure file or 
sect for a section. 


¢ file_suffix (also known as a file type or file extension) identifies the type of 
file: HLP, SSDML, .PS and so on. 


For example: 


USER_ENV_CHAP.SDML 
USER_SCREENEDIT TABLE.SDML 
REF EDIT SECT.SDML 

REF EDIT CELL_SECT.SDML 
REF PIECHART FIG.PS 


Use the following guidelines for naming files: 


¢ Choose file names that are meaningful and unique. This is important 
for the localization team and for storing and managing your files in a file 
management library. 


¢ Use the same file-naming conventions across an information set. 


e Try to use the same file-naming conventions across related information 
sets. 
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¢ Do not use numbers or letters that indicate location (such as CHAP1, 
APPB) rather than content. If the information organization changes, you 
have to rename all the files. 


¢ Do not use order numbers in file names. Because order numbers for one 
component may vary from country to country, using order numbers in file 
names could force each country to rename the files. 


5.6.8 Usability Studies 


If you are going to devise formal usability studies for any component of the 
information set, include the following in the information plan: 


e Constraints 
Describe any limitations that affect the study, such as restrictions on time 
or expenses, the availability of suitable participants, the availability of the 
product or a prototype. 

¢ Testing methods 
List the appropriate method for each goal and explain why the method is 
suitable. 

e Testing goals 
List separate goals for each component you intend to test. 


See Section 13.2 for more information on planning usability studies. 


5.6.9 Internationalization 


The Internationalization section of the plan gives an overview of the plans 
for translating the information or modifying it for a given region. Some of 
the information is repeated in other locations of the plan, but summarize the 
information here for easy reference for the localization team. 


If there are no plans for localization or translation, state that explicitly. 

All Digital products, including the user information, should follow the 
internationalization guidelines in the Digital Guide to Developing International 
Software and Developing International User Information. However, if you know 
that the user information will be localized for the current version, you can then 
set up certain procedures to ensure that the localization team has the material 
it needs. 


If your project will be localized in some manner, discuss the following topics: 
e Which components will be localized 
e Source file naming conventions 


e Tools 
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¢ Templates 


For example: 


We will design and write the information set for an international 
audience, complying with the various internationalization and 
translation guidelines. 


The Introduction to DECproduct will be adapted for the GIA market. 
The source files will use the following naming convention: 
book_subject_element.file suffix 


See Section n.n for details. 


We will use templates to write the following components: 


o The DECproduct on ULTRIX Installation Guide will use the ULTRIX 
IG template, available in: 


NODE: :DOC$TEMPL:ULTRIX IG TEMPL.SDML 


o The DECproduct on OpenVMS Installation Guide will use the 
OpenVMS IG template, available in: 


NODE: :DOC$TEMPL:OPENVMS IG TEMPL.SDML 


We will use VAX DOCUMENT™ Version 2.0 to produce the user information. 


The information group will use CMS as the file management tool. 


See Section n.n for more information on tools. 


In addition, identify the member of the information team responsible for 
coordinating translation work and the person responsible for working with 
translators. Within Digital, these are known as the translation coordinator 
and ISE User Information Engineer. Summarize the responsibilities of each 
person. For example: 


Translation Coordinator 


The translation coordinator for DECproduct Version 1.0 is Susan 
Schlecter. 


The translation coordinator has the following duties: 


oO Facilitating communication between the information team and the 
ISE UI engineer 


oO Negotiating and coordinating the schedule for delivering source 
files and artwork 
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o Distributing review drafts to ISE and collecting comments 
o Reviewing the ISE User Information Plan 


o Reviewing the information set for conformance to 
internationalization guidelines 


If necessary, the translation coordinator will provide the UI 
engineer with the following information: 


o Notice of changes to this information plan that occur after signoff 


o Hard copy of the information marked for color and showing the 
placement of artwork 


o Information on the design of the information set, including 
templates, modularity, core information, and so on 


o Comments on the post-project report written by the UI engineer 


ISE User Information Engineer 
The ISE UI Engineer for DECproduct Version 1.0 is George Leclerc. 
The UI Engineer has the following duties: 


o Sending online copies of the ISE User Information Plan to the 
translation coordinator for review 


o Communicating with the information team through the translation 
coordinator 


o Confirming receipt of hard copies of drafts, art, or other materials 


o Providing the translation coordinator with a copy of any 
post-project report on the localization project 


5.6.10 Staffing and Reviewing 


Most information plans combine the list of information team members 

with the list of reviewers for the information components. (The component 
reviewers may be different from the information plan reviewers, and different 
components may have different reviewers, depending on the reviewers’ areas 
of expertise.) Indicate which reviewers have signoff responsibility for the 
components. 


The technical reviewers are the technical experts responsible for developing the 
product. On engineering projects, this includes the engineering project leader 
and engineers. See Section 6.6.1 for more information on technical reviewers. 


The informational reviewers include members of other project teams related 
to your project. They also include anyone who is interested in knowing about 
your product. If you are working on product information, be sure to include 
the training developer for the product. Likewise, training plans should include 
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product information team members as reviewers. See Section 6.6.2 and 
Section 6.6.3 for more information on editorial and user reviewers. 


If you do not list the information plan reviewers on the title page of the 
information plan, list them in this section. 


In the staffing and review list, include each person’s function, name, and 
electronic mail address. 


Figure 5—2 shows the staffing and reviewing section of a sample information 
plan. 
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Figure 5-2 Sample Information Plan Staffing and Reviewing Section 


Table 2 describes the staffing and reviewing requirements for all components of the 
information set. Asterisks mark the individuals with signoff responsibility. 


Table 2: Staffing and Reviewing Requirements 


Information Group Reviewers: 


Writer 

Writer 

Editor 

Writing Supervisor 
Writing Manager 
Editing Supervisor 
Editing Manager 
Translation Coordinator 


Technical Reviewers: 


Engineering Supervisor 
Engineering Project Leader 
Engineer 

Engineer 


informational Reviewers: 


Engineering Manager 
Product Manager 

DECinfo Information Group 
ISE Ul Engineer 

Training Development 
CSSE 

SQM 

Marketing 


Information Plan Review Only: 


Design/Production Manager 
Design Supervisor 
Production Supervisor 
Manufacturing Planner 


* * * + * 


* * * * 


Jacqueline Dickinson 


Mark Thomas 
Michael Moran 
Ed Perez 
Joanne Cassone 
Kent Douglas 
Pat Grabowski 
Susan Schlecter 


Anna Suazo 

Jon Wilkes—Jones 
Wendy Barton 
Sonia Rojas 


Jason Chang 
Frank Callahan 
Cindy Arakelian 
George Leclerc 
Rick McGrath 
Sheela Agarwal 
Karl Szabo 
Elaine Gleason 


Maggie Kotches 
Phil Stylianos 
Pauline Lessard 
Bethany Taylor 


NODE::JDICKINSON 
NODE::MTHOMAS 
NODE::MMORAN 
NODE::EPEREZ 
NODE::JCASSONE 
NODE::KDOUGLAS 
NODE::PGRABOWSKI 
NODE::SSCHLECTER 


ANODE::SUAZO 
ANODE::WJONES 
ANODE::BARTON 
ANODE::ROJAS 


ANODE::CHANG 
BNODE::FRANKC 
GNODE::ARAKELIAN 
CNODE::LECLERC 
DNODE::MCGRATH 
ENODE::AGARWAL 
ANODE::SZABO 
FNODE::ELAINEG 


HNODE::KOTCHES 
HNODE::PHIL_S 
HNODE::LESSARD 
JNODE::BTAYLOR 
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5.6.11 Budget 


If your group includes budgeting information in the information plan, include 
that information here. Explain which tasks are included in the costs as well as 
the costs themselves. For example: 

10.0 Project Budget 


This section describes the projected budget for creating and producing the 
information for DECproduct 1.0. 


10.1 Included Costs 


All writing costs include research, writing, and information preparation 
and coordination. 


All editing costs include substantive editing, production editing, and 
online review. 


All production costs include formatting and design, graphics consulting 
and preparation, and archiving. 


Any travel costs outside of normal interplant travel are not part 
of these writing costs and are assumed by the funder. 


10.2 Estimated Costs 


The following costs are based on the estimated page counts and 
estimated schedule and are subject to change if the project plans 


change: 

Task Group Cost 
Writing $37 000.00 
Editing $10 000.00 
Production $ 5 000.00 
Total cost $52 000.00 


These costs do not include the cost of printing, which the funder 
agrees to handle separately. 


5.6.12 Tools and Equipment Requirements 


Production and localization groups need to know what tools you plan to use 
in developing your information set. List every tool that the team members 
will need and what it will be used for, including tools for file maintenance 
(such as a file management library). Using a file management library not only 
gives you a daily history of changes but also lets you rebuild information for 
different product versions or different time periods. If you plan on using any 
unsupported tools, explicitly state that in this section and explain why. 
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5.6.13 


Developing International User Information discusses issues surrounding tools 
and internationalization. 


In addition, the project needs or the tools you must use may require special 
equipment beyond your terminal. For example, the writer may need an account 
on the system being documented to test examples, or the graphic designer may 
need to use a special type of workstation to use the graphics editor needed for 
the project. 


If you need any privileges, printers, accounts, systems, disks, or other 
hardware or software, list them and briefly describe why they are needed. 


The engineering project leader, your supervisor, and your system manager can 
help you determine what you need. You may also include requirements for 
special training in this section or create a separate section. For example, the 
writer may need to take a certain programming course, or the graphic designer 
may need time for learning a new tool. 


Milestones 


The milestones section of the information plan lists critical project dates and 
dates specific to developing the user information. The information dates are 
derived from the critical project dates, which are usually nonnegotiable. 


Some groups list the critical project milestones and major information 
milestones in the master information plan and then list milestones specific 
to each component in the component information plans. For example, the 
master information plan might list: 


¢ Dates when different product base levels will be available 


e Dates of project readiness reviews, or, for projects following the Phase 
Review Process, phase closure dates 


e Date when code is frozen, that is, when development stops on all portions 
of the product that will be visible to the user 


e Date when the master information plan will be approved 

¢ Dates when all information will be ready for field test 

¢ Date when the last information component is ready for manufacturing 
e Product shipment date 


Each component information plan then concentrates on the milestones specific 
to that component: 


¢ Component information plan signoff 


e Begin and end dates for each formal review 
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¢ Production date 
¢ Manufacturing delivery date 


If the information is being localized, the component information plans also 
include milestones for the following tasks: 


¢ The date when the translation coordinator sends the information plan to 
the internationalization group 


¢ The date when the translation coordinator sends the art list to the 
internationalization group 


¢ The date when the translation coordinator transfers the source files to the 
internationalization group (usually several weeks before the components 
are delivered for manufacturing) 


If you have both hardcopy and online information (for example, books on 
CD-ROM), your schedule may include additional milestones for tasks such as 
the following: 


¢ Testing and reviewing online material. You may list separate milestones 
for different stages of testing, such as testing by the writer, review by the 
technical and editorial reviewers, and review by the production group. 


¢ Confirming delivery on a particular media. For example, your group may 
need deadlines for declaring that a particular information set will or will 
not be released on a CD-ROM. 


¢ Submitting files for online media. Your group may have milestones for 
when materials must be submitted for release on a particular media, 
such as a CD-ROM. For example, sometimes installation guides must be 
submitted at one time and other online information at another time. 


Table 5-2 lists the information milestones specific to the user information and 
specific to Digital processes. Key tasks are highlighted. The milestones are in 
approximate chronological order; the table separates the information by the 
phases in the formal Phase Review Process, but the tasks and the order are 
also valid for projects that do not follow that process. 


Use the table as a guide to develop milestones appropriate for your project. 
Depending on the nature of your project, you may not need all the milestones 
listed in Table 5-2. For example, the table lists quality assurance milestones 
for Digital software groups to submit files to the Software Quality group; your 
group may not need such milestones. You may also need to add milestones. 
For example, your group may separate the approval of outlines from the 
approval of the information plan. If so, then add a separate milestone for the 
approval of outlines. 
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In listing the milestones in your information plan, use actual dates, not TBS 
or when available, particularly in the final plan. The people reviewing the 
information plan need real information, even if it is your best guess given the 
information you have. You can indicate that some dates are unstable. For 
example, put (Estimated) or an asterisk (*) next to dates likely to change. 
You can also emphasize that your dates depend on the project dates and that 
changes in the project dates will affect the information schedule. 


Table 5—2 Milestones in the Information Plan 


Process 

Phase Milestone Comments 

Define Preliminary information plan The preliminary plan is a draft; some sections 

(Phase 0) available may be blank, and others may be subject to 
further research. 

Design Information plan approved Approval of the plan is a requirement for Phase 

(Phase 1) (signoff) 1 closure in the Phase Review Process. 

Develop Begin writing first drafts This includes both hardcopy and online 

(Phase 2) components. 


Begin developing artwork Group practice determines the exact milestones 
for when rough art is submitted to the graphic 
designers and when finished art must be 
completed. For example, your group may 
require that first drafts have rough art, field 
test drafts have more polished art, and signoff 
drafts have completed art. 


(continued on next page) 
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Table 5—2 (Cont.) Milestones in the Information Plan 


Oe eee OO’ oa 


Process 


Phase Milestone 


Comments 


Begin first draft review 
(hardcopy and online) 


First draft review comments 
due 


Begin first draft review of 
installation guide (IG) 


First draft IG comments due 
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At the minimum, distribute the first draft to 
the editorial and technical reviewers. Other 
reviewers may also be interested in the review. 


It is usually a good idea to stagger the dates 
for the review of multiple components within a 
set. Therefore, your milestones table may list a 
begin and end review date for each component 
in the set. 


In general, schedule 2 weeks for the first 
review because the reviewers must closely 
scrutinize the organization and content at this 
stage. (If the component is large, you may need 
to allow longer than 2 weeks.) See Chapter 6 
for more information on formal reviews. 


Writing the installation guide is frequently 
one of the last major tasks before the field test 
deadline because critical information is not 
available any sooner. Review the draft 2 weeks 
before the field test deadline. Note the missing 
information, and fill it in when it becomes 
available. 


(continued on next page) 
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Process 
Phase 


Milestone 


Comments 


Deliver 
(Phase 3) 


Submit field test drafts to 
copy center 


Submit online information 
for field test 


Submit information to field 
test administrator 


Give copies of information to the 
Software Quality group 


Before this date, work with the field test 
administrator to find out how many copies will 
be needed for field test. 


On this date, submit the hardcopy information 
to the copy center. Depending on your site, the 
copy center may need at least a month’s notice 
of this date. 


The installation guide is often sent to the copy 
center after the other hardcopy components 
because the material is not ready until a few 
days before the field test release date. Some 
teams choose to make their own copies of the 
installation guide. 


Submit online modules and reference pages to 
the engineering project leader so that the files 
can be built into the kit. 


On this date, submit all hardcopy information 
to the field test administrator. The administra- 
tor is responsible for distributing the copies to 
the field test sites. 


This is a requirement for software information. 
When field test begins, a copy of the 
information must go to the quality group. 
(Often the engineering project leader is 
responsible for the submission.) Include the 
installation guide, online help (optional), and 
any preinstallation letters. This submission 
lets the quality group give early feedback on 
this information and can make the final signoff 
process smoother. 


(continued on next page) 
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Table 5-2 (Cont.) Milestones in the Information Plan 


Process 
Phase Milestone 


Comments 


Begin second draft review 
(hardcopy and online) 


Second draft review 
comments due 


Begin field test review of index 


End field test review of index 


Submit field test update 
drafts to copy center 


Submit online information 
for field test update 
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Second draft review often coincides with the 
field test review. As for the first draft review, 
circulate material to at least your technical and 
editorial reviewers. Informational reviewers 
may also want to see the components at this 
stage. As for the first draft review, you may 
stagger the dates for the review of the multiple 
components within a set. 


In general, schedule 2 weeks for the second 
draft review. See Chapter 6 for more 
information on formal reviews. 


Some groups schedule a separate editing pass 
of each component’s index. This allows the 
editor to concentrate more fully on increasing 
the usability of the index. Schedule at least a 
week for each component in the set. 


If you are providing hardcopy drafts of 

any components for the field test update, 
submit those components for copying on this 
date. Depending on when the installation 
information is updated, you may need to 
have a separate milestone for submitting 
the installation guide to the copy center. 


Submit online help files to the engineering 
project leader so that the files can be built into 
the kit. 
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Process 


Phase Milestone 


Submit field test updates to 
field test administrator 


Submit final artwork to 
production group 


Information freeze 


Begin signoff review 


Signoff review comments due 


Signoff 


Comments 


On this date, submit all hardcopy information 
to the field test administrator. The administra- 
tor is responsible for distributing the copies to 
the field test sites. If you also have an internal 
formal review scheduled at the same time, you 
are responsible for distributing copies to those 
reviewers. 


All art must have been submitted to the 
graphic designer by this date. The graphic 
designer on the team can help determine this 
date, which varies according to group practice. 
It is usually some weeks in advance of the 
production start date so that the artwork is 
completed before the information begins final 
production. 


This milestone applies particularly to the 
hardcopy and Bookreader components of the 
information set. After this date, changes 

are allowed in the information sources only 
after negotiation. In most cases, the changes 
are included in the release notes. For large 
information sets, you may need to freeze 

some components earlier than others. The 
information freeze date is usually the same day 
as or shortly after the product code freeze. 


All hardcopy components and the online help 
must be approved by the signoff reviewers. 
Deliver hard copies of each component and of 
the online help to the signoff reviewers. Allow 
at least 1 week for the final signoff review. 


Signoff signifies approval of the user 
information. 


(continued on next page) 
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Table 5—2 (Cont.) Milestones in the Information Plan 


Comments 


This date is determined by the engineering 
schedule for building software kits. The 
online help files must be ready before the 
kit building begins. Negotiate the date with 
the engineering project leader. 


The production group must create print 
specifications several weeks before the 
hardcopy components are delivered for 
manufacturing. This allows the manufacturing 
group enough time to find the proper film 
supplier for the job. See your manufacturing 
representative for details on submission 
deadlines. 


This is the deadline for submitting all hardcopy 
components for final production. The date 
depends on your group’s processes and the size 
and complexity of the job. The members of 

the information team negotiate the production 
date. Large projects often have a staggered 
schedule for final production. 


This is a requirement for software information. 
The engineering project leader submits this 
kit to the quality group. Provide a hard copy 
of the installation guide and any letters with 
preinstallation information. The quality group 
reviews the information to ensure that their 
field test comments were addressed. 


Process 
Phase Milestone 
Online help freeze 
Submit print specifications to 
production group 
Begin final production 
Product assurance kits to the 
Software Quality group 
Deliver Delivery to manufacturing 
(Phase 4) 


Product shipment date 


This date marks the end of final production. 
For the information group, this is the date 
when the hardcopy components are delivered to 
the film supplier for mastering. 
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5.6.14 Dependencies and Risks 


The Dependencies and Risks section lists the events that might affect the 
information project. Identify any known risks to the quality, schedule, or 
production of the information. For example, you might be relying on the 

availability of new techniques, equipment, or tools. 


If your information uses screen captures, mention the need for a stable user 
interface. For example, if the engineering team changes a menu item as you 
are doing your final screen captures or the client updates a dynamic database, 
your schedule and the accuracy of the information may be jeopardized. 


This section may contain the following topics: 

e Any product-specific dependencies. 

¢ Dependencies on the availability or support of tools and equipment. 
¢ Dependencies on certain types of training. 


¢ Changes to the project planning documents that affect the focus of the 
project. Such changes can affect the commitments stated in the information 
plan, such as a major change in audience definition. 


¢ Changes to the milestone dates for software and hardware design, 
development, testing, and release. Changes in specifications and delays in 
development milestones mean a corresponding change in the information 
schedule. 


e Changes to the requirements from product management or manufacturing. 
Packaging plans are based on these agreements and may need to change. 


¢ Changes to the product after the agreed-on feature freeze date. 
e Changes to the project staffing. 
e Insufficient access to and time with technical experts. 


¢ Lack of promptness and quality of reviews of all information. (See 
Chapter 6 for more information on handling draft reviews.) 


¢ Acknowledgment of unusual or difficult project circumstances. For 
example, an information team may be located in widely separated 
geographic locations, or the team may belong to separate funding 
organizations. 
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5.6.15 


5.6.16 


For each risk, list a corresponding contingency plan. Thinking about what you 
will do before something goes wrong helps the team more easily change course 
if the problem does occur. It is also a means of making the rest of the project 
team aware that their actions can complicate or delay the information and thus 
the project. 


Sometimes you have no choice but to slip the schedule, but this has serious 
ramifications for the project. The team needs to examine alternatives. For 
example, if the project is understaffed, can certain books be delayed until the 
next product release? Can you cut one of the review cycles? 


Be aware of the impact of schedule changes on all the functions. For example, 
if a writing milestone is missed for whatever reason, there may be an effect 
on the editing and production groups as well as on manufacturing. Because 
they are working with multiple projects, these groups may not be able to 
change their schedules. The contingencies for handling these types of schedule 
problems need to be stated explicitly in the information plan. 


Standards Compliance and Waivers 


List all standards with which the information must comply, including both 
company standards and external standards (such as American National 
Standards Institute [ANSI] or International Organization for Standardization 
[ISO] standards). Following ISO standards is extremely important to ensure 
product acceptance worldwide. Compliance with ISO standards is becoming a 
business and technical requirement, particularly in Europe. Your company’s 
standards may increasingly comply with ISO standards. 


See Section 3.4 and The Digital Style Guide for more information on complying 
with standards. 


Also indicate whether you need a waiver from a particular standard. For 
example, there are Digital packaging standards that information sets must 
conform to. In some cases, product needs require a waiver. If external 
customer needs require you to get a waiver, ask the customer to state the 
requirement in writing. 


Before applying for a waiver, check with the internationalization team to make 
sure that the planned action is applicable and usable worldwide. 


Project Maintenance 


Include a statement about how the information team will handle reader 
comment cards, information-related product problem reports, and other 
feedback from customers after the product release. See Chapter 8 for more 
information on project closure. 
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9.7 Production and Packaging Plans 


Include details about the information production and packaging. This material 
can be either part of the overall information plan or, for large, complex projects, 
a separate plan. If it is a separate plan, send the production and packaging 
plan to the same set of reviewers as the information plan. 


You will not have all the production and packaging information you need at the 
preliminary information plan stage and may not have all the information for 
the final information plan. Supply as much information as you can for the final 
information plan. When all the information is complete, update the plan and 
send it to the signoff reviewers, production representatives, and manufacturing 
representative. 


5.7.1 Component Production and Packaging Information 


Table 5-3 explains the type of packaging and production information to include 
for each component of the set: 


Table 5-3 Component Production and Packaging Requirements 


Category Description 

en Se ee 

Distribution source The group that will manufacture and distribute the 
information set. 

Manufacturing number (if Your manufacturing group may assign a number to 

appropriate) a project for tracking it through the manufacturing 


process, from forecasting through inventory. If 
there are separate numbers for different types of 
kits, be sure to identify all the relevant numbers. 


Order number Identify the order number or part number assigned 
to the component. 


Submission method The way the information will be submitted 
for manufacturing: electronic documentation 
mastering? hardcopy reproduction package for film 
mastering? electronic submission for low-volume 
printing? 


Format The name of the format (doctype, style) used to pro- 
cess the component, such as the SOFTWARE.REF 
and HELP doctypes or the Manual and Technical 
Journal styles. 


(continued on next page) 
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Table 5-3 (Cont.) Component Production and Packaging Requirements 


Category 


Description 


Tools 


Approximate block count 


Binding method 


Spines 


Tabbed dividers 


Covers 


Trim size 


Color 


Page count 


Graphics details 


If the production and packaging plan is separate 
from the rest of the information plan, include a 
discussion of the tools to be used for creating all 
text and graphics as well as any file management 
tools. 


The block count helps the production and 
localization groups plan for more efficient 
processing. 


The way the component will be bound, such as 
perfect-binding or saddle-stitching or in a ring 
binder. 


Indicate the number of spines needed for perfect- 
bound books and the details for what is printed on 
the spines. Indicate the number of spine inserts for 
ring binders and the details of what is printed on 
the spine inserts. See Section 5.7.2 for examples of 
specifying spines. 


Indicate whether or not the component will use any 
tabbed dividers. If it will, give details on how many 
and of what type. 


Indicate whether the front cover of a hardcopy 
component is flush or tabbed. If the front cover will 
use a graphic, describe what is needed. 


Indicate the trim size of the component, such as 7 
inches by 9 inches or A4. 


Indicate whether or not multiple colors will be used. 
If they will, give details about which colors and how 
they will be used. 


Indicate the estimated page count. 


In as much detail as possible, indicate the number 
of new, revised, and existing art pieces needed. 
Estimate the number of screen captures that will be 
used. Will any of the art need to be converted from 
hardcopy to electronic form? Are there complex 
tables or examples that need production support? 
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If your production and packaging plan is separate from the information plan, 
also include the following information in the production and packaging plan: 


The name of the manufacturing group contact 


The delivery media for each component (hard copy? online book? online 
ASCII files?) 


The tools to be used for creating and managing all components 


You may also need to give more information based on how your group works. 
For example, additional project numbers may be needed. 


5.7.2 Component Kitting Information 
Hardcopy components are sometimes grouped into logical and physical kits: 


A product may be divided into logical units targeted towards different 
audiences. For example, the user information for a database management 
system may be sold in three different kits. The full kit contains all the 
user information, but the database administration and programming kits 
contain different components, as shown in Figure 5-3. 


Ring binders can usually accommodate more than one book. The 
information team can decide to place multiple books in a binder, thus 
forming a physical link between the books. (The books usually share a 
logical connection as well.) Groups of binders may also form a logical kit. 
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Figure 5-3 Logical Kitting Sample 


| Introduction 


Database Administration Programming 


Installation Guide 


Release Notes 


Database 
Design Guide 


Programming 
Guide 


Security Guide 


Maintenance and 
Performance 
Guide 


Programming 
Reference 
Manual 


Database 
Load/Unload 
Guide 


Quick Reference 
Guide 


Database 
Administration 


Reference Manual 
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If your information set is divided either logically or physically, you need to 
outline the kitting structure. Include a table or drawing in the plan that shows 
each kit. 

For example: 


This product will be sold in two kits, a user kit and a system manager 
kit ° 

The User kit (Kit number nnnnn-GZ) has two binders and two spine 
inserts. The installation guide is packaged with the software kit. 
Binder 1: 2-inch (Order number nn-nnnnn-nn) 


Spine 1: DECproduct 


User Information 


Getting Started 
User's Guide 
Binder 2: 14-inch (Order number nn-nnnnn-nn) 


Spine 2: DECproduct 


User Information 
Reference Manual 


The System Manager kit (Kit number nnnnn-GZ) has one binder 
and one spine insert. The installation guide is packaged with the 
software kit. 


Binder 1: 2-inch (Order number nn-nnnnn-nn) 


Spine 1: DECproduct 


System Manager 
System Tuning 


Troubleshooting 
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Draft and Review Process 


While the technical experts design, build, test, and revise 
the product, the information team goes through a similar 
iterative process: 


e The writers develop their drafts, send the drafts through 
informal and formal reviews, and revise the material based 
on the review comments. 


e The editor works with the writers to develop the drafts and reviews 
successive changes. 


e The graphic designer develops the art, sends it to review by the writers 
and editor, and revises the art based on the reviews. 


Often, the process of creation-review-revision starts before the project plans 
are approved. Any changes in the plans or schedules may cause further review 
and revision. 


Reviews are the major quality assurance method for information, the means 
by which the project team members and users comment on the accuracy of the 
information. Reviews also ensure that the information’s organization, design 
techniques, and explanations make the information, and thus the product, 
usable. 


There are two types of reviews: 


e Informal reviews involve only a selected set of reviewers and usually focus 
on small sections. Informal reviews may be scheduled in advance with the 
selected set of reviewers. 


¢ Formal reviews are scheduled well in advance and invite all interested 
reviewers to comment on all aspects of the information. Field test reviews 
are a special type of formal review in which the product’s customers test 
both the product and the user information. 


This chapter discusses: 


e Steps in the draft and review process (Section 6.1) 
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¢ Hints for getting started on a first draft (Section 6.2) 
¢ Types of reviews: informal (Section 6.3) and formal (Section 6.4) 
¢ Preparing for formal reviews (Section 6.5) 
e¢ What reviewers look for (Section 6.6) 
¢ Additional reviewing methods: 
— Peer reviews (Section 6.7.1) 
— Review meetings (Section 6.7.2) 
— Formal document inspections (Section 6.7.3) 
e Incorporating comments from formal reviews (Section 6.8) 


¢ Special requirements for field test review (Section 6.9) and online review 
(Section 6.10) 


¢ Formal signoff (Section 6.11) 


6.1 Steps in the Draft and Review Process 


The writer follows a set of steps in creating and revising the drafts, as shown 
in Figure 6-1. 
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Figure 6—1 Steps in the Draft and Review Process 


Incorporates signoff review comments and prepares 
for production. 


Send drafts to signoff review. 
Prepares the information for signoff. 


Makes final revisions. 


Sends the drafts to customer field test sites and to 
formal review among the technical, editorial and 
and informational reviewers. 


Revises the drafts based on the comments from co 
formal review. Continues developing the information. [ 


Sends the drafts for formal review among the 
technical, editorial, and informational reviewers. 


Revises the drafts based on the comments from 
informal review. Continues developing the 
information. 


Writes first drafts. Circulates drafts to the technical 
reviewers and editor. 


6.2 Facing the Blank Screen 


After the initial planning and research, the time finally comes for the writer 
to face the blank screen and begin writing. How does the writer begin? The 
following are suggestions for getting started and continuing the writing 
process: 


e As a beginning premise, the writers can work from the outline in the 
information plan, bringing to bear all the knowledge gained from the 
research into the product and audience. As the draft develops, the writers 
may make changes in the organization of the material. For example, 
one topic may need to be linked to several topics instead of just one, and 
another topic may need to be divided into subtopics. Thus, the writers use 
the outline as a starting point but should not be be afraid to make changes 
to it. 
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Remember that a first draft is a draft, not the finished product. The 
writers work with the material they have, concentrating on clarifying 

the purpose and audience and refining the organization and content as 
they develop the material. During the draft process, the writers identify 
where they need more information, examples, and graphics; it is acceptable 
to leave blank spaces or notes on material to be supplied later. Drafts 
often contain notes to reviewers asking if a paragraph correctly explains 

a process or concept. Drafts also contain questions from the writer about 
perceived inconsistencies in the product as well as suggestions for technical 
changes. 


The nature of the material may determine the completeness of a particular 
draft. For example, the first draft of reference information may be more 
detailed than the draft of task-oriented material because of the level of 
detail available in the project planning documents. 


The order in which the writers create sections depends on the order in 
which the technical experts develop the product. By following the flow of 
the product development, the writers can more likely test the portions of 
the product they are writing about. 


Flexibility is important. As the process continues, the writers probably do 
not work in a linear progression through the sections of the outline. The 
writers may move between modules and components depending on the 
material available at any one time. In addition, a writer’s chief resource, 
the technical expert responsible for that section of the product, may not be 
available at the exact time the writer needs the information. The writer 
then needs to move on to another section and return to the material when 
the technical expert is available. 


What happens if the writer develops a creative block? The writer may: 
— Put the material aside 

— Take a walk 

— Work on another component or section 

— Go back to the project planning documents for more ideas 

— Use the product prototype 

— Think about the usability studies for the user information 


— Talk with internal users 


In addition, writers should remember that they do not work in isolation. 
A writer can discuss the problem section with the other writers on the 
project, the editor, and the technical experts. 
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Then the writer can return to the section with a fresh perspective. 


6.3 Informal Reviews 


Informal reviews generally involve no more than several modules or a chapter. 
For example, an informal review may mean working with the technical expert 
to clarify the accuracy of a section. Informal reviews occur throughout the 
product development cycle; they are an in-process check that the writer 

is developing the material correctly and that the information is accurate, 
appropriate, and clear. 


While there are many methods of conducting informal reviews, writers may 
want to set expectations about the informal reviews for a particular project or 
component. For example, a writer may let the informal reviewers know that 
they will receive six modules every month. 


During informal reviews, editors work with the writers on the following items: 


e Organization 
In the same way that writers may change the outline as they write, editors 
look at the structure of the information as the writers develop the text. 
What made sense in an outline may look different as the information 
becomes more detailed and as the editor sees the different components in 
the set. The editor examines the order of information and the relationship 
of the parts to the whole and suggests ways to reduce redundancy and 
move material from one section to another or one component to another. 


e Clarity . 
The editor helps the writers ensure that the ideas are presented clearly, 
that users can use the information to accomplish their tasks. The 
editor also makes suggestions about the terminology and links between 
information. 


¢ Method of presentation 


During informal reviews, the editor also makes recommendations about 
how information is presented: How much detail should be included 
given the team’s assumptions about the user? What material is more 
appropriately presented as figures, tables, or examples? What material is 
more appropriately presented on line? 
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6.4 Formal Reviews 


Formal reviews give the opportunity to comment on the user information 
to everyone who has a technical interest in the project or who can provide 
insights about how the customers may use the information. Formal reviews 
have a wider scope than informal reviews: 


The number of reviewers is larger for formal reviews. 


The material being reviewed is generally more extensive. For example, 
during informal review, the writer may circulate only certain modules as 
they are developed. At formal review, all completed modules are sent for 
review. 


The number of formal reviews and their timing vary according to project 
circumstances. Ideally, schedule three formal reviews for each component of 
the information set: 


First draft review 


Second draft review (which may coincide with the field test review 
discussed in Section 6.9) 


Signoff review 


It is also a good idea to schedule a separate editorial review of the index for 
each component. The index review allows the editor to focus on the index 
itself, making sure that entries are complete and accurate. 


See Section 5.6.13 for information on the milestones for formal reviews. 


6.5 Preparing for Formal Review 


Formal reviews are not spontaneous events. The information team must: 


1. 
2 
3. 
4 


5. 


Update the list of reviewers 
Write the review cover letter 
Prepare the review drafts 


Have copies made of each review draft (the time needed depends on your 
site’s copying practices) 


Distribute the review package 


The complexity of the project usually determines who is responsible for each of 
these tasks. 
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6.5.1 Checking List of Reviewers 


Depending on the amount of time between the approval of the information 
plan and the first draft review, the list of reviewers in the plan may need to 
be updated. Different people may now be responsible for certain functions, 
and additional reviewers may want to see the drafts. (The regular project 
team meetings and your ongoing project research are the best sources of 
changes.) Check that you have the correct information about the reviewers’ 
office locations and electronic mail addresses as well as the functions they 
represent. 


6.5.2 Writing the Review Cover Letter 


The review cover letter lets reviewers know what you expect of them during 
the draft review. Include the following information in the cover letter: 


¢ The title of the component. 
e The date when review comments are due. 


e What type of review you are expecting, what the reviewers should be 
looking for. 


¢ Where to return review comments. 


e The online location of the review material (that is, the file specification or 
path name of the material to be reviewed). This is particularly important 
for reviewers at different sites. 


Example 6—1 shows a sample review cover letter. 


You may also include information on the status of the draft or project. For 
example, the cover letter may state that Chapter n is sketchy, awaiting the 
information from the next base level, or the letter may raise questions about 
whether the information is correct for the stated audience. 


You may write separate cover letters for different types of reviewers. Call their 
attention to sections important to them. 


It is also helpful to include the distribution list for the review with the cover 
letter. Reviewers may have ideas about who should be looking at the draft, 
and having the distribution list lets them check that all necessary names are 
included. 


Consider sending the review cover letter to the reviewers before the review 
period begins. This notice reminds them of their obligations and sets 
expectations in advance. 


Draft and Review Process 105 


Example 6-1 Sample Review Cover Letter 


To: Reviewers of DECproduct SQL reference help topics 
From: Jacqueline Dickinson 
Date: July 15, 1991 


Subject: Upcoming Review of DECproduct SQL reference help topics 


The first draft review of the DECproduct SQL reference help topics 
begins on: 


MONDAY, JULY 22, 1991 
Review comments are due back to me on: 
MONDAY, AUGUST 5, 1991 


Please deliver your comments to my office (RB33-26), send them to 
me at mailstop RB33-20, or send electronic comments to me at 
NODE: :JDICKINSON. 


Technical reviewers: Please review the text, syntax, and examples for 
accuracy. Is the terminology correct? Is the information technically 
complete? 


Editorial reviewers: Please review the material for organization, 
completeness, usability, accessibility, consistency, style, and 
method of presentation. Are the topics broken out sufficiently? 


User reviewers: Is the material appropriate for the intended audience? 
Are the examples and explanations clear? 


Please note the following: 


o The information on data types is a placeholder; I’m waiting for 
more information. 


oO Does the concept of "streams" apply? 
o Is there too much information on correlated references? 


On July 22, I will distribute copies of the draft material to the 
signoff reviewers (marked by a * on the attached distribution list). 
Other reviewers can copy the material from: 


NODE: : DiskN: [ DECPRODUCT.PUBLIC]SQL_REF.TXT or .PS 


(continued on next page) 
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Example 6-1 (Cont.) Sample Review Cover Letter 


Distribution: 


Technical Reviewers: 


Ruth Linden 
Sonia Rojas* 
Jon Wilkes-Jones* 


6.5.3 Preparing the Review Draft 


The draft you circulate for formal review should be as complete as possible. 
The easier it is for reviewers to read the draft, the more complete and helpful 
their comments will be. 


You can take several steps to make the review go more smoothly: 


If the tools you use include spelling and style checking components, use 
them before the review so that superficial errors do not detract from the 
substance of the information. Technical reviewers can then concentrate 

on the accuracy of the material, and editorial reviewers can focus on the 
organization, style, and clarity of the material. 


If possible, for any draft after the first draft, mark changes since the 
last draft so that reviewers can easily see the changes. (Many authoring 
tools have the capability to use change bars or some other character to 
mark sections of text that have changed.) However, if there are radical 
differences between the first and second drafts, marking changes is 
impractical. Note the nature of the changes in the review cover letter. 


Make sure that primary reviewers in particular have copies of their 
comments from the previous review. The previous review copies give 
context for the changes, letting the reviewers check the new material 
against their previous concerns. 


Be considerate of the reviewers’ schedules. Try not to schedule formal 
reviews when the technical experts are facing deadlines or when key 
reviewers will be away. Notify your primary reviewers ahead of time of 
formal reviews. If a review must fall at a busy time, allow a longer review 
cycle or distribute sections of the draft at different times. You may also 
consider having a longer review cycle for certain reviewers that you know 
are very thorough. 
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Include artwork in drafts as soon as possible. If you cannot include finished 
artwork in the draft, include a rough sketch or a copy of a similar piece 

of art with a note about what you plan. If you wait until the last minute 
to have art reviewed, you risk delay over pieces that must be changed. 

If necessary, you can have the art package reviewed separately from the 
review draft, but the signoff copy should contain the finished art in place 
with the text. 


Update packages (sets of loose replacement pages) are increasingly rare, but 
they do occur. The review draft for an update must give enough context so 
that reviewers can judge the accuracy of the changes and the effect on the 
organization. Use the following guidelines: 


Make the changes to information in the source files and clearly mark the 
changed sections. For review, distribute the whole book or only the pages 
with changes, but give reviewers enough of the draft so that they know 
how the update pages fit into the document as a whole. 


Clearly indicate text to be deleted. Reviewers need to see what is being 
removed before they can agree that deleting it is appropriate. 


6.5.4 Distributing Review Copies 


There are a variety of ways to distribute copies for formal review. Use the 
methods that best suit your project. 


Place a copy of the review draft and its accompanying cover letter in a 
public directory. Use the same directory for all the components of a project. 
It is a good idea to supply files that can be printed on different output 
devices (for example, both ASCII and PosTScriPT® files), depending on the 
reviewers’ resources. 


Give a hard copy of the review cover letter and draft (the review package) 
to each signoff reviewer. Personally distribute the draft package to each 
signoff reviewer. If your signoff reviewers are at another site, notify each 
reviewer by phone or electronic mail that the review package is coming. 
You can then send the review package through your facility’s express mail 
service or have reviewers copy the file with the review package. 


In most cases, send electronic mail to the other reviewers with a copy of 
the review cover letter and the online location of the review package. The 
reviewers then make their own copies of the review package. However, if 
you particularly value or need the comments of an informational reviewer, 
distribute a hard copy of the review package to that person. 


If you have a small list of reviewers, you may make hard copies of the 
review package for each reviewer and distribute the copies. 
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¢ ‘You may also make a number of hard copies of the review package available 
in your office. Notify informational reviewers that copiés are available and 
where. (However, also give the online location of the review package for 
reviewers who want to make their own copies.) 


6.6 What Reviewers Look For 


Reviewers look at different aspects of the review draft depending on their 
own interests and areas of expertise. While some reviewers have multifaceted 
talents, there are three general types of reviewers: 


e Technical reviewers 
e Editorial reviewers 


e User reviewers 


6.6.1 Technical Reviewers 


The technical reviewers are the technical experts whose work is most closely 
related to your material. For example, the technical reviewers may include the 
engineers and engineering supervisor for the project. The technical reviewers 
may also include at least one person from each group working on related 
projects and technical experts who used to work on this product. 


Technical reviewers make sure that the information: 
e Accurately describes the product and the system 


¢ Uses technically correct terms and examples that are appropriate to the 
product and audience 


e Is technically complete for the intended audience 
¢ Describes all necessary commands, statements, messages, and so on 
¢ Describes system limitations and trade-offs 


e Warns what happens if the product is used in a way that conflicts with the 
intended use - 


6.6.2 Editorial Reviewers 


The project editor is the chief editorial reviewer. Other people on the review 
list may also contribute editorial comments, such as the information team 
project leader, other writers on the project, writing and editing supervisors, 
writers on related projects, or internationalization representatives. 
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The editor has distinct areas of concern during the formal review stages. The 
editor and writers may decide to focus on different aspects at different review 
stages, as shown in Table 6-1. 


Table 6-1 Types of Formal Edits 
Type of Edit 


Formal Review 


First draft review 


Second draft 
review 


Signoff review 


Substantive edit: purpose, audience, organization, clarity, con- 
sistency, usability, accuracy, accessibility, method of presentation, 
appearance, and style 


Depending on the extent of changes from the first draft, may 
concentrate on style, clarity, and consistency or be a complete 
substantive edit 


Copy edit: grammar, punctuation, spelling, capitalization, 
consistency 


Table 6—2 describes the elements of an editorial review. 


Table 6—2 Elements of an Editorial Review 


Category 


Purpose 


Audience 


Organization and 
completeness 
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Details 


Is the purpose of the information clearly stated? Do users 
know what they can expect from this component? 


Does the component fulfill its stated purpose? 


Is the audience well-defined? 


Does the component contain the right level of detail for the 
defined audience? 


Are the tone and style appropriate to the audience? 


Is information in the right place? Should it be moved to 
another section or another component? Is information 
repeated within a component or across components within 
a set? 


Is information divided appropriately? 


(continued on next page) 


Table 6—2 (Cont.) Elements of an Editorial Review 
Category Details 

e Is the method of development logical for the stated purpose 
and audience? Is the arrangement consistent? 

e Is the pattern of development easily recognized? Can the 
users easily find what they need? Do titles show the pattern? 
Is the pattern consistent? 

e Is the content relevant to the stated purpose? 

e Is the material necessary and sufficient? Is there irrelevant 
information? Is each topic complete? Are all necessary pieces 
of information (installation procedures, error messages, 
glossary entries, and so on) included? 

e Are topics incomplete or needlessly repeated in several parts 
of the component or set? 

e Are elements of the same topic scattered throughout the 
component or the set? 

e Are appendixes used appropriately? 

Clarity and e Are new terms defined and used consistently? Are technical 
consistency terms used only when necessary and are they explained well? 


Should the terms be defined in text or the glossary? Do the 
definitions follow good glossary practice? 


e Are abbreviations and acronyms defined? 

e Is any information misleading or ambiguous? 

e Are main points properly stressed? 

e Is there enough overview and introductory material? 


e Are all chapters introduced consistently? If one chapter has a 
list of topics at the beginning, do the rest of the chapters? 


e Are procedures broken down into clear steps? Are the results 
of each step clear? (See The Digital Style Guide for more 
information on writing procedures.) 


e Are concepts explained clearly and unambiguously? 


e Does the information follow the appropriate corporate and 
formal standards? 


(continued on next page) 
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Table 6-2 (Cont.) Elements of an Editorial Review 


Category 


Details 


Are like items (such as titles or labels) presented in the same 
way? Are chapter and section titles parallel? Are list elements 
parallel? 


Do all elements follow the correct format? 


Does the text follow the conventions listed in the preface? Are 
there any conventions missing from the preface? 


Usability 


Is the tone appropriate for the stated audience? 
Is the information broken into small, easily grasped pieces? 


Are there enough figures, tables, and examples? Are they 
clear? Is there sufficient explanatory text to accompany them? 
Are there redundancies between them and the text? 


See The Digital Style Guide for detailed information on 
figures, tables, and examples. 


Does the information follow the elements of proper style? Does 
it reflect proper grammar, syntax, spelling, capitalization, and 
punctuation? (See The Digital Style Guide for details of 
Digital style.) 


Does the information make appropriate use of basic constructs 
such as lists, notes, and tables? 


Technical 
accuracy 


Are syntax and symbols used consistently and correctly? 


Are procedures complete and logically ordered? 


Do the figures and examples match the text? Do they match 
the product? 


Does the information seem technically consistent and 
complete? 


Accessibility 
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Is there a table of contents? Does it contain the appropriate 
level of detail? 


Do the titles accurately summarize the content of the sections? 


(continued on next page) 


Table 6—2 (Cont.) Elements of an Editorial Review 


Category Details 


Are the cross-references useful and accurate? Are there too 
many or circular cross-references? 


Does the information make good use of navigational cues? 


Is there an index? Are the entries complete? Are concepts 
covered as well as items? Are entries consistent? Are 
subgroupings appropriate? Is there adequate cross- 
referencing? Are index entries handled consistently across 
the information set? (See Chapter 10 for information on 
creating effective indexes.) 


Is online information presented effectively? Are topics of the 
right length? Does the material make effective use of white 
space, tables, and graphics? 


Do online topics have missing links? Are there unnecessary or 
confusing links? 


See Chapter 12 for more information on using navigational 
cues to improve users’ access to information. 


Design elements e 


Are the layout and typographic design effective? Is the overall 
design appropriate for the intended audience and purpose? 
Does the design make effective use of white space, margins, 
type selection and size, and so on? Does the design use visual 
cues effectively? 


Do the figures contribute to the usefulness of the information? 


Is the information presented in charts and figures clearly 
presented? Is it complete? 


Are the charts and figures neat and consistent in design? 
Are the charts and figures positioned effectively and correctly? 


Internationalization e 


Can the information easily be localized? 


Does the information avoid the use of culture-specific 
examples or icons? 


Does the information segregate country-specific information? 


(continued on next page) 
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Table 6-2 (Cont.) Elements of an Editorial Review 


Category Details 


e Are art labels produced for easy translation? For example, are 
labels placed outside the figure elements? 


See Developing International User Information and The 
Digital Style Guide for details of developing information 
that contributes to the goals of internationalization. In 
addition to extensive guidelines on creating international 
information, Developing International User Information 
contains translatability checklists for easy reference. 


6.6.3 User Reviewers 


The project editor reviews the information from the users’ point of view; your 
review list should also include groups that work with customers: 


¢ Training 

¢ Field test administrator 

¢ Manufacturing 

¢ Product management 

e Marketing 

¢ Customer support specialists 


Try to encourage these groups to return review comments. You may make 
arrangements to have certain reviewers look at particular sections and to 
discuss their comments with you on the phone or in person. 


User reviewers review the information to ensure that: 


e The preface defines the audience, the prerequisite information, and how to 
use the information 


¢ The terminology, style, and overall presentation of the information are 
suitable for the stated audience 


e The examples are clear 
e System messages are clearly explained and contain recovery procedures 
e The descriptions of features are neither optimistic nor misleading 


e The stated result of using a feature is verifiable 
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6.7 Additional Review Methods 


You can also use other review techniques to supplement the feedback you 
receive from informal and formal review or to make the review process more 
effective. The following sections discuss: 


e Peer reviews (Section 6.7.1) 
e Review meetings (Section 6.7.2) / 


¢ Formal document inspections (Section 6.7.3) 


6.7.1 Peer Reviews 


Peer reviews are another type of internal review, a means of getting feedback 
from a committee of experienced colleagues. The peer reviewers usually have 
experience with a variety of types of information and different audiences 

and thus bring a broad view to the work. In addition, because they are not 
associated with the particular component, the peer reviewers provide objective 
feedback. 


A peer review committee consists of representatives from the different user 
information functions: writing, editing, graphic design, and production. The 
committee members agree to provide feedback on information submitted for 
their review. (Submitting information to the committee is usually voluntary. 
However, in some organizations without editorial support, peer review may be 
mandatory. ) 


The peer review committee should have a moderator, who has the following 
responsibilities: 


¢ Scheduling meetings (many groups hold evaluation meetings once a month) 
e Finding projects to review 
¢ Distributing the information to be reviewed 


e Moderating the evaluation meetings and presenting the findings to the 
responsible writer 


While a meeting between the writer and the peer reviewers lets the 
participants talk face to face, holding a meeting may be impractical if the 
people involved are widely dispersed. In these cases, try teleconferencing or, if 
all else fails, having the reviewers send comments directly to the writer. 


The following list describes the steps in the peer review process: 


1. The project writer supplies a hard copy of the draft to the moderator 
along with a pointer to the online file so that the committee members can 
copy the file. The writer also provides a background memo summarizing 
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the purpose of the information, the intended audience, and any special 
information about the draft. 


2. The moderator notifies the committee members of the location of the draft 
and background memo and the details of the evaluation meeting. 


3. Before the evaluation meeting, the committee members review the draft 
using the criteria the group has agreed on. (See Section 6.6.2 for suggested 
criteria.) Committee members write their comments on the copies of the 
review draft. 


4. The committee meets with the writer (and other members of the informa- 
tion team as appropriate) to discuss comments and recommendations. This 
is not a page by page review; rather, the members discuss the component 
as a whole in terms of its organization, clarity, and so on. The writer 
receives the hard copies of the draft with the reviewers’ comments. 


5. The moderator solicits comments from the writer about the usefulness of 
the review both at the end of the evaluation meeting and after the writer 
has had time to look at the comments from the committee members. This 
feedback helps the committee to refine its process and the quality of its 
work. 


6.7.2 Review Meetings 


Review meetings provide a means of resolving and recording technical 
comments from multiple reviewers. They are an effective way to resolve 
conflicting review comments or to ensure that you receive comments from key 
reviewers. If there are conflicts, everyone can work at a solution together 
rather than having the writer move back and forth between reviewers one at a 
time. 


The writer, key technical reviewers, and the editor participate in the review 
meeting. If appropriate, the writing project leader or writing supervisor can 
run the meeting to ensure that the meeting runs smoothly and that the writer 
can copy down all the review comments. 


The following list describes the steps in the review meeting process: 


¢ Ifyou know that you will hold review meetings, mention the meetings in 
the information plan. Include them in the list of milestones, and discuss 
the need for participation in the Dependencies and Risks section. 


¢ In the review cover memo, clearly indicate when the review meeting will 
be held and the purpose of the meeting. Also note that, if reviewers cannot 
make it to the meeting, they must notify you and give you their comments 
the day before the meeting. You then have the comments at the review 
meeting. 
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If the information component is large and certain reviewers are responsible 
for only certain sections, divide the review meeting so that certain sections 
are reviewed at specific times. For example, plan to discuss Part I from 
9:00 to 10:00, Part II from 10:00 to 11:00, and Part III from 11:00 to 12:00. 
Clearly state the schedule in the review cover memo. 


e Send a reminder to the participants the day before the meeting. 


e Bring extra copies of the draft to the meeting as well as any comments 
previously submitted. 


e At the beginning of the meeting, clearly state that the purpose of the 
meeting is to gather and resolve technical comments on the particular 
information component. 


e Review the component page by page. 


Keep the discussion focused on the issues. The review meeting is neither 
the time nor the place to redesign the product. If such discussions occur, 
ask the reviewers to take care of the matter after the meeting. Likewise, 
let the editor handle editorial issues as the editing subject matter expert. 


Almost all issues can be resolved at a review meeting. If an issue cannot 
be resolved, make it clear that it is an action item, who is responsible for 
the item, and follow up to make sure you have resolution. 


¢ Incorporate all comments on a single copy of the draft. The writer has a 
master copy of the changes approved by the group. The reviewers have 
their own review copies and can compare them with the next draft. 


6.7.3 Formal Document Inspections 


A document inspection is a formal, highly structured method of internal 
review by a team of individuals familiar with the information. The inspection 
process evolved from group reviews of software code and is now used on all 
types of documents, from planning documents to user information components. 


The process works best on components that are beyond the first draft stage. 
In addition, because the review meeting involves a line-by-line reading of 
the material, the process is best suited to small modules or components. (In 
general, the team can go through 250 lines of text in an hour.) 


The goal of the inspection is identify, record, and classify problems in the 
component being inspected so that the writer can then revise the material. 
The inspection process is not intended to be a time for brainstorming, deciding 
on strategy, or evaluating the writer’s performance. The focus is on the 
information, not the people involved in the process. 
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A document inspection team consists of four to five members, all familiar with 
the material to be inspected: 


e Moderator 
The moderator has the following responsibilities: 


— Selecting the inspection team 
— Setting up the inspection review meeting 


— Making sure that the team members have all needed materials for the 
inspection and are prepared for the review meeting 


— Providing a clean copy of the material being reviewed and the problem 
report forms to the inspection recorder 


— Functioning as an inspector 


— Running the review meeting and ensuring that the members stay 
focused 


— Circulating the problem report forms to the team members after the 
meeting 


e Reader 
The reader has the following responsibilities: 


— Functioning as an inspector 
— Reading the component aloud at the review meeting 


e Recorder 
The recorder has the following responsibilities: 


— Functioning as an inspector 


— During the review meeting, marking a copy of the component for the 
writer and recording the problems on the problem report forms 


e Inspectors 


The inspectors (including the moderator, reader, and recorder) have the 
following responsibilities: 


— Reviewing the cover memo and any supporting material before the 
review meeting 


— Thoroughly reviewing the information component before the meeting, 
using certain codes to note problems (see Table 6-3) 


— Participating in the review meeting 
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e Writer 
The writer has the following responsibilities: 


Preparing an overview memo before the inspection, which summarizes 
the purpose of the component, the intended audience, and any special 
information about the material 


Sending a hard copy of the component to the moderator and supplying 
the location of the online file so that the inspection team can print out 


copies 


Participating in the review meeting 


Revising the component based on the comments from the review 


meeting 


The document inspection methodology divides problems into four major 
categories. Table 6—3 lists the categories and describes the codes within each 

~ category. It lists the Problem Type (Category 3) codes applicable only to text; it 
does not list the codes applicable to program code. 


Table 6-3 Document Inspection Problem Categories and Codes 


Category Code 

1. Visibility? VI 
IV 

2. Presence MS 
EX 
WR 


3. Problem Type AM 


Meaning 


Visible to the end user of the product or service 


Invisible to the end user of the product or service 


Missing 
Extra 
Wrong 


Ambiguous statement or antecedent 
Explanation or definition; incomplete information 


Contradiction of goal of this project or a problem with 
the goal statement in the source document 


Inconsistency in statements in the component 


Legal requirement 


This category is applicable only to program code. 


(continued on next page) 
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Table 6-3 (Cont.) Document Inspection Problem Categories and Codes 


Category Code 
NS 


OR 
OT 
RR 
SC 
SP 


4. Quality CM 
Dimensions? 


PK 


Meaning 


Information not specific enough for intended audience 
and purpose 


Organization, overall structural problems 
Other 

Redundant wording 

Semantic content, meaning unclear 
Spelling 

Style convention 

Syntax, sentence structure, punctuation 


Information too specific for intended audience and 
purpose 


Typography, visual appearance 
Use of language, miscellaneous reasons; grammar 
Verbosity 


Vocabulary, choice of words 


Compatibility 


Constraints, trade-offs 

Cost 

Conformance to standards 
Environment 

Esthetics 

Features 

Human factors, usability, ease of use 
Maintainability 

Packaging 


“This category is useful mainly for demonstrating progress towards meeting a set of quality goals. 
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(continued on next page) 


Table 6-3 (Cont.) Document Inspection Problem Categories and Codes 


Category Code Meaning 


PR Performance 
RE Reliability 
T™T™ Timeliness 


The following list describes the steps in the document inspection process: 


1. 


10. 
11. 


The moderator plans and prepares for the inspection, including estimating 
the amount of time needed for the review meeting and selecting the team 
members. 


The writer gives a hard copy of the draft to be reviewed to the moderator, 
along with the overview memo and any necessary supporting information. 
The writer also supplies the online location of the files so that the team 
members can print them out. 


The moderator sets up the review meeting and notifies the team members. 
The moderator supplies the team members with any added information 
they need (such as the problem categories and codes). 


The inspectors thoroughly review the information component. 


A day or two before the meeting, the moderator checks to make sure that 
the inspectors are prepared for the meeting. If they are not prepared, the 
review meeting is postponed. 


At the review meeting, the reader reads aloud the draft, line by line (except 
for boilerplate information). 


The inspectors raise problems as they occur, and the team classifies the 
problem. 


The recorder records the problems on the problem report form and marks a 
copy of the draft for the writer. 


At the end of the meeting, the team decides whether another inspection is 
needed after the writer revised the draft. 


The writer receives the problem report form and the marked-up draft. 


The moderator creates a summary report for management. The report 
contains the name of the document, the list of participants, the time it took 
for the inspection process, and the reinspection decision. 
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12. The moderator also creates a quality control report, which includes a 
summary of the problem types by category. 


6.8 Incorporating Review Comments 


After each review period, the writer must evaluate the review comments 
and revise the draft based on the comments. Including comments from just 
ten review copies can be a large task, so the writer should begin processing 
comments as soon as they are received. 


The writer can add some comments directly to the draft. However, many 
comments require that the writer: 


¢ Rewrite passages to make them clearer 
e Investigate technical questions 

¢ Research user practices further 

¢ Decide among conflicting comments 


Often the writer must do more research and use the product even more than 
for the first draft. 


The writer must prioritize review comments and pay particular attention to 
the technical comments. Incorporating comments from the technical experts 
first may be most efficient: technical changes may have a dramatic effect on 
the material, making some other comments irrelevant because the section has 
been deleted or radically changed. 


6.8.1 Responding to Comments 
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Reviewers like to know that the writer has considered their comments. If the 
reviewers know that they have been heard, they are more likely to give useful 
comments on future drafts. 


As writers go through review copies, they can take a moment to mark the 
review copy so the reviewer knows what action was taken on the comment. 

A checkmark or word or two is enough: “OK,” “thanks,” “project leader 
disagrees,” “no time — will consider for later,” and so on. Once the writers 
have gone through the review copy and decided how to incorporate the 
material, they may then return the review copies to the reviewers. The 
reviewers then know that their comments have been considered and can still 
talk with the writers if they disagree on issues. The reviewers also have their 
comments in hand when they review subsequent drafts. 
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6.8.2 Handling Late Review Comments 


Most reviewers are conscientious about returning review comments on time. 
However, some reviewers may have other commitments that cause them to 
miss the deadline. Writers can use several techniques to ensure responses to 
review: 


¢ Some reviewers are chronically behind schedule. The writer can try to get 
the drafts to these people early. 


e The writers can call or visit late reviewers. 


e If the draft is long, key reviewers are unavailable, or some project 
milestone has slipped, the writers can extend the review date and notify all 
reviewers. 


e If important reviewers have other commitments and cannot return 
comments on time, the writers can make arrangements for those reviewers 
to look at only certain sections. 


e If all else fails, the writers can make arrangements to meet with the late 
reviewers and go over the draft. 


Writers should keep their project leader and supervisor informed if there are 
chronic problems with late comments. The project leader and supervisor can 
work with the funding or technical group to resolve the problem. 


If the team has established good working relations with the reviewers before 
the draft stage, the reviewers know their opinions are important and will 
cooperate as much as possible. 


Some useful comments will come in too late to incorporate into the current 
draft. In this case, the writer can incorporate the change into the next review 
draft. If the comment was from the signoff review, the writer can consider 
making the change in the next version or, if it is a substantive technical 
change, adding the material to the product release notes. 


6.9 Field Test Review 


Field test review is a special type of formal review in which the product and 
the user information are sent to selected customers. Field test gives the user 
information team the opportunity to get feedback from the people who use the 
information to install, run, and maintain the product. The terms Alpha test 
and Beta test are also used to refer to the concept of field testing. 


The purpose of field test is to: 


e Find errors and omissions in the product and the user information before 
the product is released 


Draft and Review Process 123 


¢ Verify that the user information is complete and accurate 
e Verify that installation procedures are correct 
¢ Make sure that the product works and performs as intended 


The length of field test varies from project to project, and a given project may 
have multiple field tests (known as field test updates or FT1, FT2, ... , FTn). 
Field test customers may also particiapte in field test training, which provides 
information about new product features. The training period varies, from 1 
day to as many as 5 days. 


An individual on the product team is usually responsible for choosing the field 
test sites based on the criteria in the project planning documents. The field 
test administrator looks for customers who will test the product in ways that 
the product is expected to be used in the real world. The administratoris also 
responsible for getting the product, including the information, to the customer 
sites and polls customers for feedback, reporting the results to the technical 


group. 


6.9.1 Improving Results from Field Test Review 


Unfortunately, during field test, customers tend to test the product more 
carefully than the user information; as a result, the information team may get 
little or no feedback. This happens for several reasons: 


e Many field test customers are already familiar with your company’s 
products. They may feel that they are familiar enough with the product so 
that they do not need to use the user information. 


¢ Accustomer support specialist is sometimes available at the field test 
site for training and assistance. As a result, customers may not have an 
incentive to use the information set. 


¢ Field test may occur relatively late in the product development cycle and, 
because of the time needed to produce and manufacture the information, 
there is little time to include useful suggestions. However, the review 
and revision cycle applies across product versions. Keep the suggestions 
from field test on file, and use them for planning the next version of the 
information. 


How can you help ensure that you get useful feedback from real users? The 
best way is to provide clear, usable, well-designed field test information. 
Include an index and as much artwork as possible. You may also: 


¢ Sit in on or participate in any field test training. Work with the 
technical group, field test administrator, and the training group for 
more information. 
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e Include the writer’s name and phone number on the field test drafts, which 
has allowed some writers to make useful contacts. 


e Send two copies of the user information, one to be returned with comments 
and one that the customer can keep. 


e Schedule an information-only field test, separate from the product field 
test. This separate test is useful if you are experimenting with a new 
approach or book. 


e Send out a questionnaire about the user information. Check to see if the 
field test administrator can distribute and return the questionnaire if you 
prepare it. You may write a separate information questionnaire or append 
it to the engineering questionnaire if there is one. 


Work with the field test administrator and product management to conduct 
a telephone interview of selected customers. 


e Visit a customer site, if time allows. Work with the field test administrator 
and product management to set up the visit. (Before you make any contact 
with customers, make sure you call the appropriate sales account manager. 
Account managers must be informed of any contact between you and 
their customers so that they can be fully informed when talking with the 
customers. You may also want to talk with the local service representative 
before the visit.) In addition: 


— Call the site in advance to make the arrangements. Clearly explain 
who you are and why you are visiting. Make sure the customers install 
the product before your visit, and request that they look at the user 
information before the visit. (If you do not clearly convey the purpose 
of your visit, you may be asked to install the product or teach how to 
use it when you arrive.) 


— Time your visit carefully. If there is no on-site training program, do 
not visit the site before the users have had a chance to use the product 
and the information. On a project with several field tests, go to a site 
in the middle of the field test cycle, if possible, so that you have time to 
incorporate the feedback into the user information. 


— Be prepared to talk about the product, not just the user information. 
Customers see you as a representative of the project as a whole. 


Even if you gather little direct feedback on the user information, the visit is 
still a valuable experience. You learn more about your audience and their 
work environment, and you see the product from the customer’s viewpoint. 


You can supplement your feedback from field test sites with feedback from 
internal users. 
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See Chapter 13 for information on designing and implementing questionnaires, 
interviews, and other usability studies for both internal and external users. 


6.9.2 Incorporating Field Test Review Comments 


Incorporating field test comments is similar to incorporating comments from 
formal review. However, you may not be able to discuss the comments with the 
reviewers. Rely on your best judgment about which comments to incorporate, 
combined with advice from your key reviewers. If you have developed a good 
relationship with several customers (through site visits, for example), then you 
may be able to use a more personal approach in discussing comments from field 
test. (However, be sure to coordinate this contact with the product manager 
and sales account manager before talking with the customer.) 


In addition to comments from your own field test questionnaires and site visits, 
you may also receive comments through the technical group or the group that 
manages the field test. 


Some of these comments deal directly with the user information, while others 
deal with the product; product changes, however, usually mean changing the 
corresponding section of the user information. If field test comments point out 
a problem with the user information, you must answer the comments. Ask 
your supervisor about how to receive and respond to such comments. 


6.10 Online Information Review 


6.10.1 


Because of their media, online books and online help have some special 
requirements during the review process. However, it is important for the 
online information to receive the same rigorous review as the hardcopy 
information. 


See Chapter 11 and Developing International User Information for information 
on creating online information. 


Online Books 


Online books are created and processed in generally the same manner as 
hardcopy books. This is true whether the information is available both in 
hard copy and on line or on line only. The writer sends a hard copy of the 
information through the regular review process so that reviewers can examine 
it for accuracy, usability, organization, and so on. See Section 11.1 for more 
information on online books. 
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However, the information team must also regularly check the completeness 
and presentation of the information on line throughout the review cycle. Use 
the following checklist to help in this evaluation: 


Each book has the following elements: 
— Table of contents. 


— Index. (The Bookreader application does not require an index. 
However, the index is one of the main ways that users navigate 
the book, and the book’s usefulness is constrained without an index.) 


— Front matter (title and preface) that is in one file. 


The table of contents is complete and accurate. There are no duplicate 
section names. If any problems occur, check the symbolic names for 
accuracy and uniqueness. 


The topics are not too large. If they are and it makes sense to make 
them smaller, break them up into smaller topics. (See Chapter 4 and 
Section 11.1.2.1 for guidelines on dividing information into topics.) 


The informal figures, tables, and examples are not too wide for the screen. 
If they are, put them in their own pop-up window. (See Section 11.1.2.3 for 
information on using pop-up windows.) 


Each formal figure, table, and example has a hotspot in text so that users 
can access the formal element. 


The annotations are included in the pop-up windows for figures, tables, or 
examples that you want to display in a pop-up windows. Otherwise, the 
text is hidden by the graphic. 


Wherever possible, the information is presented graphically (for example, 
in lists, figures, and tables). 


The list of conventions does not say that user input is shown in second 
color (red, for example). If it does, add a sentence to say that user input is 
shown in bold for the online version. 


All user input in examples is clearly identified. 


There are no hardcoded references to chapters, sections, appendixes, part 
numbers, or formal figures, tables, or examples. If hardcoded references 
are used, delete them and use the symbolic names instead. 


The text does not overuse boldface type, italic type, or uppercase letters 
for emphasis. Such typeface changes are more noticeable on line than on 


paper. 
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6.10.2 


e The text in the book is not too dense, and the design uses sufficient white 
space. Much dense text on the screen is difficult to read. Where possible, 
break long paragraphs into several short ones, use lists to emphasize 
information, and consider replacing text with art. 


In addition, during formal reviews, the editor reviews the online books for 
style and usability, ensuring that the information is easily accessible and as 
clear, complete, and well-organized as possible. In the online review, the editor 
looks at the following aspects of the online book. Many of the questions are 
not unique to online information, but the proper use is particularly crucial for 
online information. 


¢ Do titles accurately reflect the contents of sections? Is information divided 
into the proper topics? Are topics of a manageable length? Could a topic 
be further divided? Are lists used to break up the density of text? See 
Section 11.1.2.1 for a discussion of online topics. 


¢ Does each chapter begin with a list of the topics covered in the chapter? 
Can the user get to the topics from this list? (In Bookreader, each topic is 
a hotspot, and the user is able to click on this hotspot with the mouse and 
jump to the appropriate section. See Section 11.1.2.2 for more information 
on hotspots.) 


¢ Is artwork well used? Could some text be better presented visually? Do 
figure captions define the content of the figure? 


¢ Is information easily located, either through the table of contents or the 
index? Given sample tasks that users might perform, how quickly can the 
information be found through the table of contents and the index? 


e Does the index give synonyms to help users find the information they 
are looking for? Is the index complete and well organized? Are all tasks 
represented? Using just the index, can the user find a piece of information 
with a maximum of two tries? 


See Section A.3 for more information on checking the quality of online books. 


Online Help 


Reviewing online help is more difficult than reviewing online books because 
the information may be seen out of context. However, the following suggestions 
can help make the review go more smoothly: 


¢ At first review, the writer distributes to the reviewers a hardcopy version 
of the help files and an outline of the help structure. If possible, the help 
files are also available for online review. The reviewers check the structure 
and logic of the help files. 
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e At second draft review, the writer again distributes a hardcopy version of 
the help files and an outline of the help structure. The online help files are 
also available for checking. The reviewers: 


— Test the online help by navigating through additional topics and 
context-sensitive objects. 


— Review the usability and writing style of the help frames. 


— Review the help text for proper grammar, spelling, capitalization, 
punctuation, and consistency. (The project editor is usually responsible 
for this type of check.) 

The reviewers make their comments on the hard copy of the help files and 

return the comments to the writer according to the schedule. 


e At signoff review, the writer distributes a hard copy of the help files. 
Reviewers again check the help for accuracy, clarity, usefulness, style, and 
appearance. 

After the writer incorporates the signoff review comments, the information 
team does a final check on the accuracy of the links between topics. 


6.11 Final Signoff 


Final signoff is the formal approval indicating that the user information 

is ready for production and manufacturing. It occurs after the final signoff 
review. Signoff indicates that, to the best of the signoff reviewers’ knowledge, 
the information meets the goals of accuracy, appropriateness, accessibility, 
clarity, and completeness. 


The number of reviewers with signoff authority varies with the complexity and 
type of project. Include the following functions: 


e Editing 

e Funding organization 

¢ Product manager (if there is one) 
e Technical experts 

e Writing 


As with the signoff of the information plan, the authority of individuals to 
commit to the plan may differ by functional organization. For example, the 
manager of the funding organization may be the only individual in that group 
who can sign off on the information plan, while the supervisor of the technical 
group has the authority to commit to the plan. Likewise, on some projects, 
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the functions overlap. For example, the engineering group may be both the 
funding group and the responsible technical group. 


At the end of the signoff review period, the writer meets briefly with each 
signoff reviewer to get approval. Some reviewers will not sign off if they still 
want corrections made. The writer can discuss the requested changes with the 
reviewer; often the person will sign off if they know the changes will be made. 


Managers often rely on those who are technically closest to the project to judge 
the information’s accuracy and will not sign off until the supervisor and project 
leader have signed off. Therefore, it is often good practice to get the writing 
supervisor’s signature before the writing manager’s and the funding project 
leader’s and supervisor’s signatures before the funding manager’s signature. 


The form for signoff varies by group. Figure 6-2 shows a sample form. 
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Figure 6-2 Sample Signoff Review Form 


Final Review 
Signoff Sheet 


DECProduct Guide to Programming 


Document Title Part Number 


Jacqueline Dickinson Date 
Writer 


© Editing’s signoff indicates that this material has received a full literary/style edit, 
incorporates the agreed organizational and style changes, and has been copy 
edited. The writer has incorporated the changes or has agreed to do so. 


e Writing’s signoff indicates that the material has been reviewed for content, style, 
and organization, that it meets the group’s quality standards, and that the 
material is ready for final production. 


© The technical group’s signoff indicates that the material accurately describes the 
product, the examples are correct, and the coverage is appropriate for the 
intended user. 


® The funding group’s signoff indicates that the material meets the agreed goals 
for the project and that the coverage is appropriate for the intended user. 


Editor Date 


Writing Supervisor Date 
Writing Manager Date 
Engineering Project Leader Date 
Engineering Supervisor Date 
Engineering Manager Date 
Product Manager Date 
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Production and Distribution 


The process of bringing an information set through 
production and delivering it to a supplier changes as the 
technology changes. The tasks required for preparing a 
document for delivery are constantly changing. As a result, 
Digital information groups are redefining what production 
means today, and they are modifying their methods to fit the 
new processes. 


In this chapter, production refers to the steps that are needed to prepare a 
final document for delivery to a supplier. These steps begin when a writer has 
incorporated all technical and editorial review comments and the document 

is stable. Production ends when the final document, in electronic or hardcopy 
form, has been sent to an internal organization or external supplier. 


Kach information group within Digital has its own process for handling the 
details of production, depending on the group’s needs. Although each group 
must perform the same major steps, the group may use a variety of approaches 
and methods. This chapter discusses the common elements of the different 
group processes, as well as some of the options available for delivery. The 
processes and tools described in this chapter are specific to Digital. Use the 
steps described only as a guideline; consult your own group’s production 
guidelines for specifics. 


Information groups now prepare their information sets for a variety of delivery 
methods, including the following: 


e Submission of hardcopy documents to an internal organization or external 
supplier for distribution as film or printed books (Section 7.1) 


¢ Submission of electronic files to an internal organization or external 
supplier for distribution as film or printed books (Section 7.2) 


¢ Submission of electronic Bookreader files for distribution on CD-ROM 
(Section 7.4) 


Section 7.5 briefly describes duplication, printing, and distribution services. 
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Figure 7-1 shows the process flow for these production and delivery methods. 


Figure 7-1 Production and Delivery Process 
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7.1 Submitting Hardcopy Reproduction Packages to Internal 
or External Suppliers 


A hardcopy submission or delivery means that a complete hardcopy package 
containing the repro proofs and mechanicals (or camera-ready copy) and all 
the related production material is sent to an internal or external supplier. The 
user information group is responsible for ensuring that the camera-ready copy 
is of good quality and suitable for printing. 
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Once the supplier has received the package, they produce film or printed books, 
depending on the requirements for the product. Within Digital, film is required 
for simultaneous worldwide distribution. 


7.1.1 Preparing a Final Copy of the Document 


A document is considered final when all art is in place, each page is proofread 
(if this step is required by your group), last minute edits are verified, and final 
pagination is made. 


Most documents receive some level of proofreading. The timing and 
responsibility for proofreading varies from group to group. Proofreading 

may be performed by in-house editors, contract proofreaders, or an off-site 
proofreading supplier. Proofreading comments are marked on the hard copy, 
and when proofreading is complete, the appropriate edits are made to the file. 
The marked hard copy is checked against a new printout of the file. 


The document should be processed one last time during production to ensure 
that the latest technical changes, proofreading edits, and art changes are in 
the final copy. Responsibility for performing the final build varies from group 


to group. 


The final hard copy of the document is often called the master copy or the 
repro proofs. It contains the following elements: 


¢ Title page 
¢ Copyright page 


e Table of contents 


e Part pages 
e Preface 
¢ Chapters 


e Appendixes 
¢ Index 
e Reply card and mailer 


Check the contents of the book against the table of contents to ensure that all 
pages are in the repro proofs. Also check to see that all pages are clean and 
text is straight. If there is a proprietary classification, check each section to be 
sure the proper proprietary listing is printed on each page. 


See Section A.6.1 for more information on quality standards for repro proofs. 
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7.1.2 Preparing Related Materials for Delivery 
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The delivery of an information set is simply the act of sending the final 
package to the supplier. In addition to the repro proofs, the information team 
must prepare the following items that make up the reproduction package: 
e Assembly sheet 
The assembly sheet lets the film and print suppliers know what to expect 
in the master package. The assembly sheet indicates the book covers, the 
total number of pages including blanks, the location of pages with special 
treatment (for example, color) the location of any tabbed dividers, and any 
perforations. 
e Print specification 
A print specification is a form that contains the following specifications for 
the purchasing group and the print supplier: 
— Text and cover paper stock 
— Cover specifications 
— Ink colors 
— Special considerations (photographs, bleed pages) 
— Type of binding 


— Type of film master proof 
Within Digital, the print specification may be created as a hard copy or by 
using an online program that is part of an internal electronic submission 
tool. See Section 7.2 for more information on electronic submissions. 

¢ Mechanicals 
Cover, spine, and tabbed divider mechanicals are created manually by 
the designer or by using an online program that is part of an internal 
electronic submission tool. See Section 7.2 for more information on 
electronic submissions. 

e Waiver, if necessary 
You may also need to include a copy of any waivers approving deviations 
from your company’s publishing or manufacturing standards. 

¢ Color and screen markup copy, if necessary 


If the copy requires screens or multiple ink colors, a hard copy must be 
marked up for the film supplier. 
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e Sample layout page (recto/verso page layout sheet) 
The sample layout page identifies the right and left page position. 


See Section A.6 for more information on quality standards for the components 
of a reproduction package. 


7.1.3 Preparing a Final Reproduction Package 


The final reproduction package is the complete and final package that is 
sent to the film supplier. It consists of the master copy, assembly sheet, print 
specification, waiver, color and screen markup, mechanicals, a sample layout 
page, and a folding dummy if a reference card is included. At this point, a final 
build has been performed, pasteup is completed, and the camera-ready copy is 
ready for review. 


The writer, editor, or production representative reviews the camera-ready copy 
to ensure that all parts of the component are present. It is not the time for an 
exhaustive proof of the component. 


Before sending the final package to print, make copies of the repro proofs 
because the film supplier may call with questions about particular pages. 


In most groups, a production signoff process is required before the information 
set goes to the supplier. This process may involve the collection of signatures 
from various contributors and managers, or it may be a verbal approval from 
the project leader. Follow the procedures practiced within your group. 


7.2 Submitting Electronic Files 


Within Digital, user information groups may also submit their information 
sets electronically to manufacturing using EDMS (Electronic Documentation 
Mastering Standard). EDMS is an internal Digital suite of tools that allows 
documentation to be printed from specially formatted, industry-standard 
POSTSCRIPT files. These files contain information that lets them be translated 
or processed by the film and print suppliers without the need to photograph 
camera-ready copy. EDMS provides the flexibility to go to high-volume (offset 
press) or low-volume (demand print) printing from the same set of master 
files. In addition to embedding specific formatting information within files, 
EDMS also provides different types of output. Information groups can use two 
modes for proofing, and suppliers can direct output for either film or plates. 
EDMS also includes electronic tools for developing assembly sheets, print 
specifications, and mechanicals. 
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Besides eliminating the need to prepare camera-ready copy and subsequent 
paste-up and repro packaging, EDMS also provides other benefits: 


¢ Higher quality film (1200 to 2400 dots per inch versus 300 to 600 dots per 
inch for camera-ready masters) 


¢ Lower costs 


e Reduced time to market 


7.3 Reviewing Film Master Proofs 


A film master proof is a preprint review copy of a document made from 
stripped-up film negatives. A common type of proof is called a salt or 
blueline. User information groups used to request these proofs routinely as 

a way to verify that the film was prepared properly. However, most Digital 
groups have eliminated the proof approval process, unless their information set 
contains four-color process printing. In such a case, the group can request an 
integral proof, which gives a facsimile of the final four-color process printing. 


7.4 Submitting Electronic Bookreader Files for Distribution 
on CD-ROM 


Digital information sets are distributed every other month on an OpenVMS 
or ULTRIX compact disc through the corporate CD-ROM program. The 
OpenVMS disc is released every other month, beginning in January; the 
ULTRIX disc is released every other month, beginning in February. These 
discs are commonly referred to as OLD (Online Documentation) discs. 


To participate, the information group must first create their information files 
for the Bookreader application, as described in Chapter 11. The group also 
determines on which disc and for which month their information sets will be 
released. 


A central organization within Digital handles the consolidation of the files 

for both the OpenVMS and ULTRIX discs. This group provides a schedule, 
which includes dates for when files must be submitted to them for release on a 
particular disc. 


Once an information group knows what documents they plan to submit for 
release on a disc, they fill out and submit an online form to the consolidation 
group several weeks in advance of the submission of files. This form contains 
information on file names, bookshelf titles, file size, and so forth. When it is 
time to submit the Bookreader files, the information group copies them to a 
public directory maintained by the consolidation group. 


138 Production and Distribution 


7.5 Duplication, Printing, and Distribution Services 


Many publications groups at Digital produce files or camera-ready copy and 
rely on other organizations for duplication, printing, packaging, kitting, supply, 
and order fulfillment. These organizations are here collectively referred to as 
manufacturing. Manufacturing is a worldwide network of sites responsible for 
the introduction and supply of products to customers. 


The publications groups often rely on the manufacturing group for the 
following types of activities: 


¢ Choosing suppliers for the manufacturing of film and printed books 
e Working with suppliers to ensure quality control 


¢ Packaging, kitting, storage, and distribution of information, including 
technical user information, promotional and marketing literature, course 
materials, and so on 


In Digital, different manufacturing organizations also provide services such as: 
¢ Media mastering and duplication 

e High-volume and on-demand printing 

e Mass mailing services 


¢ Collating, assembly, binding, and packaging services 
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8 


Project Closure 


The responsibilities of the information team do not end when 
the project is delivered for manufacturing. The information 
team needs to evaluate and bring the project to its proper 
close. Team members must review their individual and 
collective efforts, solicit evaluation from the funder, and 
determine how to respond to user feedback on the released 
product. 


This chapter describes the following the closure activities: 


e Reviewing the project’s success through the post-project review meeting 
(Section 8.1) 


¢ Determining the satisfaction of the funder (Section 8.2) 


¢ Responding to reader comment cards and other types of user feedback 
(Section 8.3) 


e¢ Archiving source files for future use (Section 8.4) 


8.1 Post-Project Review 


A post-project review (also known as a postmortem or postpartum) is a 
meeting that gives the people responsible for the user information the chance 
to discuss their roles on the project, identify their successes, and offer solutions 
for any problem areas. The focus of the review is on the process, not on 
interpersonal issues. 


The information team project leader or writing supervisor is usually 
responsible for arranging the post-project review meeting, though any 
member of the team may take on this responsibility. The meeting typically 
occurs within a few weeks after the information has been delivered for 
manufacturing. This delay allows enough time for the team members to reflect 
on the project but is not so late that everyone has forgotten the project details. 
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The general objectives of any post-project review include: 


Providing an equal opportunity for all members of the team to express 
their opinions. 


Assessing how well the project met its goals. 
Identifying what worked well so that those processes can be used again. 
Identifying problem areas and recommending improvements. 


Improving the quality of the information by improving the quality, 
efficiency, and productivity of the information development process. 


Comparing the estimated and actual costs of the project. Making 
recommendations to reduce costs. 


Comparing the estimated and actual time spent on the project. Making 
recommendations to reduce the time to complete a project. 


Discussing the communication flow between the different members of the 
information team and between the information team and the other project 
team members. Recommending changes to improve communication. 


8.1.1 Post-Project Review Participants 


Ideally, any member of the information team for the project should have input 
to the post-project review. 


The participants usually include the following individuals: 


Each writer on the project 

Information team project leader 

Editor 

Funding group representative 

Graphic designer 

Production specialist 

Supervisors of the different functional areas within the information group 
Technical project leader 

Translation coordinator 


Manufacturing representative 
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Depending on the size of the team and other constraints, either all members of 
the information team or a representative from each function participates in the 
review meeting. You can also add other people as appropriate for your project; 
for example, you may include the usability engineer. 


Some groups hold an initial project review meeting for the information team 
only. After the meeting, the project leader or supervisor works with the funder 
to review the group’s recommendations and gather the funder’s feedback. A 
meeting for the information team only may be helpful if: 


e The information team is very large 
¢ There were difficulties within the information team 
e There were difficulties between the information team and other project 


groups 


8.1.2 Preparing for the Post-Project Review Meeting 


The information project leader or supervisor sends a memo to the participants 
at least a week before the review meeting. The memo clearly states: 


e The purpose of the meeting 


e The order in which representatives of each function will give their feedback 
and the amount of time allotted 


The memo may also suggest areas that the representatives consider before the 
meeting: 


¢ Performance 
— Were the project objectives completed? 
— What variables enhanced or hindered the project’s completion? 


— What improvements can be made to the process to ensure the success 
of future versions? (For example, what improvements can be made to 
the review process, field test process, and so on?) 


° Cost 


— Ifa cost estimate was given, did the actual cost meet or exceed the 
predicted cost? Why? 


— What improvements can be made to help future projects meet cost 
estimates? 


e Time 


— How long did it take to complete the project? 
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— Was this time longer than was anticipated? 
— What factors influenced the schedule? 


— What improvements can be made to help future projects better estimate 
time needed? Can the information development process be made more 
efficient? 


Communication 


_— Were members of the information team well-informed about project 


goals and changes? 


— Was communication clear between the information team and the other 
project team members? 


— What improvements can be made to the process to ensure clear 
communication on further projects? 


8.1.3 Post-Project Review Meeting 


The review meeting is run by a moderator, who has the following 
responsibilities: 


Ensuring that someone takes minutes of the meeting. The minutes are 
later drafted into the post-project report. 


Beginning the meeting with a brief history of the project and a summary of 
the project goals. 


Reviewing the order in which the groups will give their feedback and the 
time allotted. 


Ensuring that each group has the opportunity to speak, that the discussion 
does not descend to the personal level, and that the group keeps to the 
problem-solution format. 


Ending the meeting with a summary of the major points made during the 
meeting. 


8.1.4 Post-Project Report 


The writing supervisor or information team project leader (or some other 
designated member of the team) writes the post-project report based on the 
minutes of the meeting. The report is then sent electronically to the meeting 
participants, who review it for accuracy and completeness. 


The written report summarizes the project for the present contributors and 
helps the information group improve its processes. In addition, the report 
gives background information for the next version of the product or for similar 
projects. 
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After the report is approved by all the participants, the writing supervisor or 
project leader archives the report with the other project documents. 


8.2 Client Satisfaction Survey 


A project evaluation survey is a closure technique designed to address a 
funder’s satisfaction with the information group’s services and processes and 
with the final information set. The survey results tell the information group 
how the funders perceive the group’s effectiveness in specific areas. 


If possible, distribute the survey electronically. Electronic distribution is faster 
than hardcopy distribution, and it is easier to collect and process the replies. 


The client satisfaction survey has the following advantages: 
e Is a low cost method of gathering feedback 


e Allows respondents can take their time to collect facts, talk with others, 
and consider replies at length 


e Is perceived as being more impersonal, thus providing the feeling of 
anonymity and, consequently, resulting in more honest answers 


However, there are disadvantages: 

e The response rate is often low. 

¢ Questions cannot probe too deeply into content. 
¢ Questions cannot be long or complex. 


The following sections discuss the types of questions a survey may contain and 
ways to improve survey results. 


8.2.1 Sample Survey Questions 


The way you design and administer your survey affects the number and 
quality of the responses. See Section 13.1, Section 13.2, and Section 13.3 for 
more information on planning and implementing surveys. See Section 13.5 for 
more information on designing questionnaires. 


Many satisfaction surveys use what is known as the Likert scale to weigh 
responses to questions. The respondents are asked to respond to each 
statement by marking one of five degrees of agreement: strongly agree, 
agree, neither agree nor disagree, disagree, strongly disagree. 
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Figure 8-1 shows a sample client satisfaction survey. 


Figure 8-1 Sample Client Survey 


Client Satisfaction Survey 
DECproduct Version 1.0 


The following survey will help the DECproduct User Information group evaluate their services and improve their processes. 
Please indicate how strongly you agree or disagree with each statement. 


Strongly Neither Agree Strongly 
Agree Agree Nor Disagree Disagree Disagree 


1. The information is well organized. 


2. The information is well written 
and easy to read. 


3. The writer acquired sufficient 
knowledge of the subject matter 
to communicate the material 
effectively. 


4. The information team contributed 
to the product design. 


5. The design and format of the Re 
information are visually pleasing. 


6. The print quality is sharp, —s 
clean, and professional. 


7. Cost and time estimates for this eee —— 
project were clear to me. 


8. The information plan milestones —s 
were met. 


9. There was effective communication oes — 
with the information team. 


10. The project’s status was 
communicated regularly. 


11. The information development 
process was well managed. 


12. The information was printed and 
distributed in a timely manner. 


8.2.2 Improving Survey Results 


Notifying participants about the survey in advance, particularly by telephone, 
is an effective way to increase the number of responses. It also tends to 
accelerate the rate of return. 
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In addition, follow-ups or reminders are a good way to increase the response 
rate. Because each successive follow-up results in added returns, you can 
gather many responses. However, you must also weigh the value of the 
additional information against the time needed for successive contacts and for 
evaluating the responses. 


8.3 Reader Comment Cards and Other Feedback 


Information groups use various means to find out what users think about the 
user information. This material not only gives feedback on the success of the 
most recent release but also serves as the foundation for the plans for the next 
version. 


For example, site visits, questionnaires, and so on are all valuable ways 
of gathering feedback. See Chapter 13 for information on designing and 
implementing different types of usability studies. 


However, there are two common types of user feedback that the information 
group must address: 


e Reader comment cards 


The reader comment card is either a separate card or a page within a 
component. The card is automatically sent to the user with the user 
information. Customers mail the preaddressed cards back, where they 
are processed and distributed to the information group responsible for the 
product. Figure 8—2 shows a sample reader comment card. 


The rate of return on reader comment cards is often low. The responses 
usually come from two extremes: those users who are very pleased with 
the information and those who are very dissatisfied. Thus, the information 
may not be totally useful in gauging the effectiveness of the information 
set. However, the comments may also give useful information about errors 
in the information. 


Respond to all comment cards. If users take the time to fill out and send in 
the cards, they deserve the courtesy of a reply. Often, you can send a form 
letter thanking the user for the comment and promising to consider the 
comment for the next version. At other times, you may need to work with 
other groups to solve a particular problem. For example, users sometimes 
receive defective documents and need to know how to get a clean copy. 
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Figure 8-2 Sample Reader Comment Card 


Reader’s Comments Introduction to DECproduct 
XX—XXXXX=XX 


Please use this postage—paid form to comment on this document. If you require a 
written reply to a software problem and are eligible to receive one under Software 
Performance Report (SPR) service, submit your comments on an SPR form. 


Thank you for your assistance. 
Information Rating: Excellent Good Fair Poor 
Accuracy (product works as document states) HH wu WH 


Completeness (enough information) Se hae 
Clarity (easy to understand) eee ee 
Organization (structure of subject matter) ==) 
Figures (useful) es ee, 
Examples (useful) Sees, fe ee 
Index (ability to find topics) a a a 


Page Layout (easy to find information) ee aes 
| would like to see more/less 


What | like best about this document is 


| found the following errors in this document: 
Page Description 


Additional comments or suggestions to improve this document: 


lam using Version_______ off the product this document describes. 
Name/Title. (Céept. 
Company___ Date 


Mailing Address 
Phone 
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Product problem reports 


Depending on their service contracts, customers may send in problem 
reports when they find problems with the product, including the user 
information. (For example, Digital software users may send in Software 
Performance Reports [SPRs].) Engineering groups are usually measured 
on how quickly they respond to problem reports. Therefore, if there is a 
problem report dealing with the user information, you need to take care of 
it as quickly as possible to avoid jeopardizing your relationship with the 
engineering group. 


Before the members of the information team go on to other projects, the team 
must assign someone to track and respond to reader comment cards, problem 
reports, and other user feedback. 


8.4 Archiving 


The last step in closing the project is archiving, saving the files and documents 
that may be needed in the future, either for reference in working on the next 
version or for recreating the information if needed. What you archive and how 
depends on your group’s facilities, tools, and processes. Use the following as 
guidelines: 


Keep the source files of the user information for the most recently released 
version of the product. If you use a file management tool for your work 
group, make sure the latest versions of the files are included and are 
identified in a way that allows them to be retrieved easily. If your 
organization has a group library, include the final versions of the files in 
that library as well. 


Depending on your group’s volume and processes, you may need to keep 
some of this information on tape or some other backup mechanism (some 
groups make multiple copies in case of problems). Clearly label the tapes, 
and make sure that someone knows where the tapes are and how to access 
the information. 


You may also archive a copy of the reproduction package for each hardcopy 
component in case you or the manufacturing group needs the materials to 
make more copies. 


Keep a copy (online or hardcopy) of the most recent user information plan 
and post-project review report. These documents provide background for 
the team responsible for researching and planning the next version of the 
information. If other planning documents were particularly insightful, you 
may also save copies of those documents. 
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¢ Keep on file constructive user feedback, such as reader comment cards 
that point out errors to be fixed in the next version or the results of user 
surveys. If the group sent out a client satisfaction survey, also keep on file 
the results from that survey. 


Whatever archiving methods you use, be sure that the team agrees who is 
responsible for each step and where the information will be kept. Also be 
sure that someone in the group understands how to access the information in 
whatever form it may be in. Otherwise, the file you desperately need will be 
the one that no one knows how to open. 
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The chapters in this part discuss the following topics: 


Terminology consistency 
Indexing 

Online information 
Navigational cues 
Usability studies 


Trademark searches 


Part Ill 


Techniques 
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Managing Terminology 


Clear technical information uses all terminology consistently 
and appropriately. The consistent use of terminology helps 
users understand the information more easily and makes the 
translation process easier. 


In a fast-paced environment like the computer industry, using 
terminology effectively is a continuing challenge. New words 
are created, grow in popularity, and become obsolete with astounding speed. 
New concepts and products are constantly developed and need new terms to 
describe them. The information team is thus faced with different types of 
problems: 


¢ The industry borrows words commonly used in the language but gives 
them a specialized meaning. For example, the word icon has taken on a 
specialized meaning in the computer industry: 


icon (Webster’s Ninth New Collegiate Dictionary) 


1. A usually pictorial representation. 2. A conventional religious image 
typically painted on a small wooden panel. . . . 


icon (Project glossary) 
A symbol that represents an application, object, process, or window. 


e Similar environments develop different terms for the same object, idea, or 
process. For example, most operating systems have similar capabilities 
for managing files, but each operating system may use different terms 
to describe the functions or objects. OpenVMS systems use the term file 
specification for the location of a file, while ULTRIX systems use the term 
pathname. 


¢ Concepts and objects are described by awkward phrases, such as floating 
underflow trap enable bit or user-customized advanced editing function. 
Groups then create abbreviations and acronyms to avoid the repetitive use 
of the long phrases. Unfortunately, both the phrases and the proliferation 
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of acronyms make the user’s understanding and translation to other 
languages more difficult. 


This chapter describes techniques you can use to ensure that your information 
uses terminology clearly and consistently: 


¢ General principles for managing terminology (Section 9.1) 

¢ General guidelines for avoiding translation problems (Section 9.2) 
e Style sheets and word lists (Section 9.3) 

¢ Glossaries (Section 9.4) 


See Appendix B for bibliographic information for reference works, dictionaries, 
and glossaries used within Digital. 


9.1 General Principles for Managing Terminology 
Use the following guidelines to maintain consistent terminology: 
¢ Use terms consistently: 


— Do not use different terms for the same object. For example, do not use 
program in one place and executable image in another. 


— Do not use the same term for different objects. For example, do not 
use the term file name to refer both to the file name field of a file 
specification and to the full file specification. 


e Define terms clearly either in the text or in a glossary. If there is any 
doubt about users understanding a term, define it. See Section 9.4 for more 
information on creating glossaries. 


e Use typographic and symbolic conventions consistently, and define them in 
a conventions table in the preface. See The Digital Style Guide for more 
information on conventions tables. 


e¢ Spell out abbreviations and acronyms at the first use in text and in 
the glossary. However, you may also want to expand abbreviations and 
acronyms at multiple points within a component to accommodate the user’s 
nonsequential reading of information. As technology changes, the concept 
of first use loses meaning as users more frequently navigate information 
in a random way. In a hypermedia environment, for example, users may 
link to the middle of an online document or to a single online topic; the 
information team cannot know if this is the first time the user has seen the 
abbreviation or acronym. 
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Use concrete language whenever possible, terms that have referents in 
the physical world. However, in describing concepts or qualities, you often 
have to use abstract words because of the abstract nature of the subject. 
Relate the abstraction to more concrete concepts that the user is probably 
familiar with. Use an illustration to let the user visualize the concept. 


Avoid catch-all phrases. Sometimes a term becomes so widely used that 

it no longer has any specific meaning. For «xample, the term hypertext 
originally meant the nonlinear navigation through a body of literature. 
The term has now come to be used as a vague way of talking about the 
future of information retrieval. If you must use a catch-all phrase, give it a 
specific meaning and consistently use that meaning. 


Avoid jargon. In its positive sense, jargon is the specialized vocabulary 
for a particular profession or industry. However, using jargon becomes a 
problem when all the members of the audience may not know a term or 
when the meaning is vague. Determining when jargon is understandable 
and when it is not is subjective. For example, the terms hardware and 
software are widely used and understood in the computer industry, but 
the terms vaporware and shelfware are not. The latter two terms are 
called jargon in the negative sense. Be aware of your audience’s level of 
knowledge. If you are uncertain about a term, look at how it is used in 
trade journals, advertisements, competitive materials, and so on. 


9.2 Translation and Terminology 


Dealing with inconsistencies in terminology is one of the more time-consuming 
tasks for translators. They must search for subtle differences in meaning that 
justify using two or more words for seemingly the same concept or pick one 
word for each concept. 


Developing International User Information provides details about using 
terminology to make translation easier. Use the following general guidelines: 


Do not create terms that allude to obscure cultural references. Translators 
are trained to change examples that are obviously culture specific but they 
may not recognize indirect references to culture-specific items or concepts. 
For example, the term blue-ribbon panel is clear only to those who know 
that a blue ribbon is sometimes used to designate the best or first in a 
class. That type of demarcation is culture specific. 


Even if a project is not being translated until the files are stable, make a 
copy of the glossary available to the translation team as early as possible. 
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e Remember that even if information is not translated, it will likely be used 
by nonnative speakers of English. Use clear, direct language, and avoid 
culture-specific terms and definitions. 


9.3 Developing Style Sheets and Word Lists 
Most groups follow a specific set of style guidelines: 


¢ The guidelines may be specific to the company or organization (defining 
what is known as a house style). For example, Digital uses The Digital 
Style Guide as its primary style reference, the resource that defines the 
Digital house style. 


¢ Whether or not the organization has a defined house style, it may also 
follow standard style reference works, such as The Chicago Manual of 
Style, Words into Type, or the U.S. Government Printing Office Style 
Manual. 


e In addition, a project may need to follow certain government or other 
formal standards that further define style guidelines. For example, ISO 
standards can affect how the information presents units of measurement. 


However, even the most comprehensive style references cannot cover all the 
elements of style that come up in an information project, and there are times 
when the information team agrees that the specific material needs a different 
type of treatment. In these cases, the project editor creates a style sheet or 
word list to control the consistency within an information set. 


9.3.1 Style Sheets 


A style sheet is a list of project-specific rules that supplement the rules 
that define house style. A style sheet usually covers the following types of 
information: 


¢ Spelling, capitalization, and punctuation of specific words and phrases 
e Abbreviations and acronyms 

¢ Bibliographic conventions 

¢ Footnote information 

¢ Numbers 

¢ Symbols 

e Trademarks and service marks 


¢ Typographic conventions 
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The project editor may also include reminders about certain elements of the 
house style; this provides an easy reference during the editorial review. For 
example, the editor may note the use of boldface type for terms that are defined 
in the text or write in a sample bibliography entry. See The Digital Style Guide 
for details on documentation conventions. 


Example 9-1 shows part of a sample style sheet. The editor usually divides a 
sheet of paper (or a file) into units for each letter of the alphabet and for other 
categories of information. 


During the review of a component, the editor notes on the style sheet any 
special spelling, hyphenation, and so on. The editor may also note the location 
of the first occurrence of the term and of discrepancies. (The location may be 
the section or page number. However, page numbers and section numbers may 
change as a draft is revised.) . 


The style sheet is a tool not only for editors. Editors supply the writers with 
copies of the style sheet so that the writers can build consistency into the 
files as they write. If the production group does a proofreading check during 
production, then the proofreader also uses the style sheet. Furthermore, when 
the project is over, the editor keeps the style sheet as a reference for the next 
version of the project. 


Example 9-1 Sample Style Sheet 


LM NO PQ 
language sensitive Adj 3-2 non-file-structured 8-11 
language-sensitive PA 1-4 

Local Area Terminal 2-8 

mailbox 1-3 


RS TU vw 

random-access memory 1-10 tie wrap N 6-13 wide area network 2-3 
shut down V 2-4 

shutdown N,Adj 2-1, 3-2 


XYZ Numbers Symbols 
zeros N pl 10 000 < left angle bracket 
10 eleven [ left bracket 
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9.3.2 Word Lists 


A word list, as its name implies, is a list of abbreviations, acronyms, and 
terms in alphabetical order. A word list gives the accepted spelling for all 
technical terms and may also include the spelling of common terms that are 
frequently misspelled or misused. Word lists may also contain brief notes 
about usage. For example: 


active insertion point -- Do not use the term current insertion point. 
active window 

A/D (analog-to-digital) 

adapter -- Do not use the term adaptor. 


A word list generally applies to more than one product. Editors compile the 
word list from the style sheets for the individual products and circulate them 
to the writers and others who need the information. 


See The Digital Style Guide, which contains the Digital word list. 


9.4 Developing Glossaries 


Glossaries are another means of ensuring consistency in terminology. 
Glossaries present terms and their definitions. There are two types of 
glossaries, differing in their intended audiences: 


¢ Project glossaries are internal glossaries that help writers, editors, 
technical experts, and other team members use terms consistently as 
products are developed. 


¢ Customer glossaries are glossaries released with an information 
component or information set. They help the customers understand 
how terms are used in the context of the particular product. Customer 
glossaries usually evolve from project glossaries. 
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Other differences between a project glossary and a customer glossary include: 


Development 
stage 


Scope 


Level of 
expertise 


Project Glossary 


Development begins during the 
project planning stages, using 
the functional specification and 
other technical research as 

a base. The project glossary 
evolves over the life of the 
project. 


May cover multiple products, 
an entire environment (such as 
computer-aided engineering), 
or a vertical industry, such as 
financial software. 


Provides definition of terms in 
context. 


Customer Glossary 


Usually developed more towards 
the end of a project, when the 
information is fairly stable. 


Usually limited to the terms 
used in a product, whether 
the glossary is a separate 
component in the set or part 
of a component. 


Discusses how a term is used, 
both incorrect usage and correct 
usage. 


For example, the following definitions show how the terms handle and select 
were defined in a project glossary and a customer glossary: 


handle 


select 


Project Glossary 


A symbol on the border of an 
object that appears when that 
object is selected for operations 
such as moving, sizing, copying, 
or deleting. 


To designate information, either 
text or graphics, that will be the 


object of a subsequent operation. 


The following sections discuss: 


Customer Glossary 


A rectangular symbol on the 
border of an overlay object 
that appears when that object 
is selected for operation such 
as moving, sizing, copying, or 
cutting. 


To designate information, either 
in text or graphics, that will 

be the object of a subsequent 
operation. You can select 
objects, such as overlays of a 
chart or data in a worksheet, by 
clicking on the objects or data. 


e Selecting and ordering glossary entries (Section 9.4.1) 


e Writing glossary definitions (Section 9.4.2) 


e Using cross-references in glossaries (Section 9.4.3) 
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See The Digital Style Guide for details on the placement and format of 
customer glossaries. 


9.4.1 Selecting and Ordering Entries 


Use the following guidelines when selecting and ordering glossary entries: 


Select terms (either single- or multiword) that are new to the intended 
audience or familiar terms that have new meanings. 


Include all acronyms used in the text. (However, if an acronym is a 
trademark, do not expand the acronym. See The Digital Style Guide for 
more information on trademarks.) 


Do not include procedures such as mount a disk or allocate a drive. 
Instead, define the individual terms (such as allocate and drive) in the 
glossary, and place the procedural topic in the index. 


Make sure that your definitions are technically accurate and usable by 
circulating the glossary for review among the technical, editorial, and 
usability reviewers. (See Section 6.6 for further information on what these 
types of reviewers look for.) 


Use the same method of alphabetizing in both the glossary and the index, 
either letter-by-letter or word-by-word. (See The Digital Style Guide for a 
discussion of the methods.) Digital prefers letter-by-letter alphabetizing. 


9.4.2 Defining Glossary Entries 


A glossary entry consists of a term and its definition. The definition consists 


of: 


A phrase describing the term and explaining how it is used. End this 
phrase with a period. 


An optional sentence or sentences further clarifying the material. 


For example: 


distribution list 
A file that contains a list of user names. You use a distribution list 
to automatically address a message to each user name in the file. 


Use the following guidelines in creating and formatting glossary entries: 


Capitalize glossary terms the same way in the text and in the glossary. 
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For example: 
Text: 


The domain associates a data file with a record 
definition. Use the Application Design Tool to.... 


Glossary: 


Application Design Tool 
A querying device that helps.... 


domain 
A data structure. ... 


Present all definitions in parallel grammatical form. Use a phrase 
beginning with A, An, or The to begin the definition of a singular noun 
or verb. For example: 

application 

A set of procedures that performs a task or function. 

logging in 

The identification of a user to the operating system. 

When you define an adjective, begin the definition with a phrase like 
Pertaining to. For example: 


synchronous 
Pertaining to related events in which all changes occur simultaneously. 


Define acronyms and abbreviations either with the shortened form or the 
spelled-out term, depending on which form is more commonly known and 
used. Use a cross-reference to the other form. For example: 

UAF 

User authorization file. A file containing an entry for every 


user that the system manager authorizes to gain access to the 
system. 


user authorization file (UAF) 
See UAF. 


Use only the most common acronyms in the definition of a term, for 
example, CPU and I/O. If you have doubts about whether the acronym is 
known, do not use it to define another term. 
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¢ Do not define a term by using that word or a variation of it in a definition. 
Use 


screen width 
The number of character positions that can be displayed on a line. 


Do not use 


screen width 
The width of a line on the screen. 


e Provide a frame of reference for the term. A definition must be able to 
stand on its own and inform the reader of the context. 


Use 


intensify 
To increase the level of brightness of all or part of a screen display. 


Do not use 


intensify 
To increase the level of brightness. 


e If two or more terms are synonomous, place the definition with the more 
frequently used term. Mention the less frequently used term after the 
definition. For example: 


captive account 
A type of account that limits the activity of the user. Also known as 
a turnkey account. 


Also include the less frequently used term in the glossary. In place of a 
definition, add a cross-reference to the more commonly used term. For 
example: 


turnkey account 
See captive account. 


Or: 


turnkey account 
Same as captive account. 


e Define meaning rather than action. Do not confuse a definition with the 
process used to create the object being defined. For example: 


style sheet 
A list that the project editor creates in reviewing a component or 
information set. 
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In this example, the meaning of the word is restricted to who creates 
the item and when it is created. If someone other than the project editor 
creates the style sheet, is it still a style sheet? Furthermore, while the 
definition places the term in a category (list), it does not explain how a 
style sheet differs from any other type of list. 


In contrast, the following definition defines the general category in which 
the term belongs and differentiates the term from other items in the 
category: 


style sheet 
A list of rules on spelling, capitalization, conventions, and so on that 
provides a project-specific supplement to the rules that define house style. 


¢ Ifaterm has multiple definitions, separate the definitions with a semicolon 
if the definitions are close in meaning. For example: 


node 
An end-point of a branch in a network; a computer system in a network. 


If the definitions are not closely related, number each definition. For 
example: 


source 
(1) The point of entry of data in a network. (2) A data terminal 
installation that enters data into a connected channel. 

9.4.3 Using Cross-References 


Use the following guidelines for cross-references in glossary definitions: 


e If you can control the format of glossary entries, typographically 
distinguish cross-referenced terms from the cross-references themselves. 
Use italic type for the cross-references (See, See also, and so on) and either 
boldface type or the regular text type for the cross-referenced term. 


Use 

See also real-time processing. 
or 

See also real-time processing. 

Do not use 


See also real-time processing. 


However, if the cross-referenced term is in italics, use the regular text type 
for the cross-reference. For example: 


See also The Chicago Manual of Style. 
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To avoid a proliferation of typeface changes, use boldface type only in 
explicit cross-references. Do not use boldface type for glossary terms that 
are used in the definitions of other glossary terms. For example: 


Use 


auto-selection 

An operation in which users select an object by moving the location 
cursor to that object using the navigation keys; no further action is 
needed to select that object. 


See also location cursor, navigation key, navigation key, selection. 


Do not use 


auto-selection 

An operation in which users select an object by moving the location 
cursor to that object using the navigation keys; no further action is 
needed to select that object. 


See also location cursor, navigation key, selection. 


¢ Use See to refer to a synonomous term: 


folio 
See page number. 


¢ Use See also to refer to a related term: 


timesharing 
A method of allocating computer time in which each process gets an 
equal amount of time in turn. See also real-time processing. 


You can use the phrase Compare with instead of See also. 


¢ Use Contrast with to refer to a term that is opposite or different, yet 
related, in meaning to the term defined. Note the use of the italics. 
input 
Information that is introduced into a program for use in processing. 
Contrast with output. 


¢ A cross-reference must always point to an existing definition. In addition, 
make sure that a cross-referencing loop is not incomplete. In the following 
example, the user is led in a circular path of cross-references and never 
sees a definition: 


pure code 
See reentrant code. 


reentrant code 
See code. 


code 
See pure code, reentrant code. 
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10 


Indexing 


The purpose of an index is to give users quick random access 
to the information they need. As such, the index is one of the 
primary means of finding the information in a component, 
and the success of the index is a major factor in how well the 
component meets the goal of accessibility. 


Some people using the index are familiar with the component 
and use the index to retrieve information. Other users have little or no 
familiarity with the component and use the index to find information and make 
connections between topics and objects. However, neither set of users wants to 
browse through the index: they want information, and they want it quickly. 


The task of the indexer is to provide a complete, accurate, and balanced index 
that meets the needs of both audiences. 


This chapter discusses: 

e Characteristics of a good index (Section 10.1) 

¢ Parts of an index entry (Section 10.2) 

¢ Steps in the indexing process (Section 10.3) 

¢ Guidelines for creating index entries (Section 10.3.3) 
¢ Guidelines for creating master indexes (Section 10.4) 


e Editing indexes (Section 10.5) 


10.1 Characteristics of a Good Index 


A useful index gives the user multiple points of entry to the subject matter and 
a balanced view of it: 


¢ Points of entry are the topic headings the indexer creates for a given 
statement in the information component. The indexer helps users by 
anticipating the topic headings users are likely to look for. 
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To generate multiple entry points, you can include synonyms for topics and 
make logical permutations of entries. For example: 


Indexes, abbreviations in 


Abbreviations, in indexes 


e An index is balanced when the entries reflect the emphasis given to topics 
in the information components. Thus, the indexer must understand the 
information well enough to know what the main topics are, how they relate 
to each other, and how much emphasis each topic receives. 


10.2 Parts of an Index Entry 
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An index entry has the following parts: 
e A primary entry, which indicates the topic 


e A secondary entry, which specifies or clarifies a particular aspect of the 
topic 


e A locator, which indicates where to find the information 


For example: 


Device names << Primary Entry 
controller designation, 3-2 : 


device codes, 3-4 Secondary Entries 


unit numbers, 3-2 
\——-———— Locator 


You may decide to highlight different components of the index entries to make 
the information more accessible. For example, you may use boldface type 

to indicate the location of the primary discussion of a topic, or you may use 
the suffix ¢ after a page number to indicate that the information is found in 
the table on that page. If you establish such conventions, include a key at 
the beginning of the index, and use the conventions consistently. However, 

do not introduce such conventions unless you can use them consistently; the 
inconsistency will confuse users rather than help them. 
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Index entries may also contain cross-references that direct users to the right 
topic or closely related topics. For example: 


Disks 
See System disks, User disks 


Cross—Reference 


There are two types of cross-references: 


e §6See 
Directs the user from one topic to the term where the index entries are 
listed. See references must always point from a synonym to the term used 
in the component. For example: 


Text editors 
See EDT Editor 


¢ See also 
Directs the user to a closely related topic or another aspect of the same 
topic. For example: 


EDT Editor, 3-1 
See also Line mode 


10.3 Steps in the Indexing Process 


Creating and polishing an index is painstaking work, requiring you to focus 
both on small details and on the broad structure of the material. You must 
create, analyze, and refine the entries themselves and determine how the index 
works as a whole. 


Although some writers leave indexing until the end of the project, it is 
generally more efficient to develop the index entries as the material develops. 
However, if you must leave the indexing until the end of the project, be sure to 
schedule adequate time to develop and revise the index. 


In your first draft of the index, do not worry about having too many entries or 
redundant entries. It is much easier to delete and consolidate entries at the 
end than to create them at the end. 


Your goal is to provide a thorough means of accessing the topics in the user 
information, and, in developing the index, it is better to err on the side of a 
generous index than a sparse index. The size of index depends on the type 

and complexity of the material, not on page count. For example, a reference 
manual may have a shorter index than does a conceptual guide because the 
reference manual consists largely of terms, such as commands, options, and 
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keywords. A conceptual guide, on the other hand, has not only technical terms 
but also concepts and procedures. However, if a language is complex, the 
language reference manual may have a more extensive index than a particular 
task-oriented book that describes only a subset of the tasks associated with the 
product. 


This section discusses the steps in creating an index: 

¢ Creating an authority list (Section 10.3.1) 

e Analyzing the text (Section 10.3.2) 

¢ Selecting primary index entries (Section 10.3.3.1) 

¢ Selecting secondary index entries (Section 10.3.3.2) 


¢ Using cross-references (Section 10.3.3.3) 


10.3.1 Creating an Authority List 


An authority list is a technique you may use to ensure the consistency of 
index entries. An authority list is a record of the correct form of potential 
index entries, noting, for example, which terms are capitalized, which terms 
are plural, and which terms are preferred (cross-references). Consistency is 
important in index entries because it increases users’ efficiency in using the 
index. The authority list is the means of ensuring consistency. 


Use the following steps to create the authority list. Much of the information for 
the authority list is already available from the style sheet and word lists the 
editor developed (see Section 9.3) and from the list of tasks developed during 
the information design stage (see Section 4.2 and Section 4.6.1). 


If possible, create an online file for the authority list. You can then use your 
system’s software to sort the entries alphabetically. In addition, you can easily 
add new topics and generate an updated authority list at any time. 


1. Begin by listing all the tasks discussed in the component. Include the 
terms associated with each task. For example, the task of creating an 
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index with a particular publishing system would begin this way: 


Indexes, stages of processing 
Indexes, how to process 

Index entries, sorting 

Index entries, merging 

Index entries, coding 
Indexes, tags for 

Indexes, changing format of 


Add any terms associated with the tasks, including the product components 
associated with the task. For example, the following list has explicit 
entries for the formatting tags and qualifiers associated with the software. 
Also include synonyms for terms. 


For example: 


X tag 

Y tag 

INDEX qualifier 

Page numbers <--synonym for locator 
Page numbers, range of 

Locators <--synonym for page number 
Cross-references 

Headings, for index 

INX files 


Include any other contexts in which the task might be performed. These 
other contexts may be useful cross-references. For example: 


Indexes, See also Master Indexes 


Include entries for the concepts contained in notes, cautions, or warnings. 
For example, if the text contains a note that online indexes do not contain 
page numbers, you might include the following entries in the authority list: 


Page numbers, and online display 
Online books, index, page numbers in 
Indexes, online display 
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5. Continue this process for each task associated with the product. When you 
are finished, you have a list that looks something like this: 


Indexes, stages of processing 
Indexes, how to process 

Indexes, online display 

Indexes, See also Master Index 
Index entries, sorting 

Index entries, merging 

Index entries, coding 

Indexes, tags for 

Indexes, changing format of 

X tag 

Y tag 

INDEX qualifier 

Page numbers 

Page numbers, and online display 
Locators 

Cross-references 

Headings, for index 

INX files 

Master indexes 

Online books, index, page numbers in 


6. Sort the list of topics to produce an alphabetical list. 


Also see Section 10.3.3.1 for further details on what items to include in the 
index. 


10.3.2 Analyzing the Text 


Once you have the authority list, you can begin adding index entries to the 
information source files. However, you need to analyze the text as you create 
the entries. The information is not presented in units of equal size, nor is all 
of it equally important. There may be pertinent information in one clause in a 
sentence, in one short paragraph, or in three or four paragraphs. One section 
may have 20 entries and another only 2. . 
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Using the authority list as a guide, consider the emphasis in the text. For 
example, suppose you need to index the following information: 


The TYPE command displays a file at your terminal. To 
display a file named TEST.DAT, enter the following 
command string: 


$ TYPE test.dat 
This is the first line of a file created with the EDT™ editor. 


While a file is being displayed, you can stop and 

resume the upward movement, or scrolling, of the terminal 
display by using Ctrl/S and Ctrl/Q. To temporarily stop the 
display from scrolling, press Ctrl/S; to continue the 
scrolling, press Ctrl/Q. (The No Scroll key on VT100 terminals 
and the Fl key on VT200-series terminals perform the same 
functions. Pressing No Scroll once stops scrolling; pressing 
it again resumes scrolling.) 


You could create all these index entries for this section: 


Files, displaying on terminal 
TYPE command, example 
Scrolling, defined 

Scrolling, resuming 
Scrolling, stopping 

Ctrl/S, function of 

Ctrl/Q, function of 

No Scroll key, function of 

Fl key, function of 


You need to analyze the text to see which entries are significant to the section. 


The information on the TYPE command is insignificant in this context; it does 
not tell users anything about the command except that they use the TYPE 
command for displaying files. If they know to look up the TYPE command 

in the index, leading them to this page gives them no useful information. At 
most, you might have an entry for: 


Files, displaying with TYPE command 


In addition, the information about the keys may not be pertinent to the 
discussion, particularly if the information appears in a table or appendix 
elsewhere in the component. 
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10.3.3 


10.3.3.1 


What you have left are four entries: 


Files, displaying on terminal (or Files, displaying with TYPE command) 
Scrolling, defined 
Scrolling, resuming 
Scrolling, stopping 


If there is no other information about scrolling in the component, you may 
consolidate these entries when you edit the index. Either of the following 
entries is acceptable: 


Scrolling, how to control 
Scrolling 


As you begin to enter index entries in your files, it is better to have too many 
entries than too few. You can always remove the superfluous entries, but it is 
more difficult to add entries at a later date. You cannot fill in gaps that you 
cannot see. 


Creating Index Entries 
This section lists the guidelines to follow when creating entries for your index: 


¢ Creating primary entries (Section 10.3.3.1) 
¢ Creating secondary entries (Section 10.3.3.2) 
¢ Using cross-references (Section 10.3.3.3) 


Use the same method of alphabetizing in both the index and the glossary, 
either letter-by-letter or word-by-word. See The Digital Style Guide for a 
discussion of the methods and for additional information on the format of index 
entries and the placement of the index in a component. 


Creating Primary Entries 
Use the following guidelines when creating primary entries: 


¢ Always create primary entries for the following types of items: 
— Acronyms 
— Commands 
— Concepts 
— Examples 
— Figures 
— Options, qualifiers, switches, and keywords 


— Parameter names 
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— Procedures 

— Routine names 

— Standards such as IEEE or ANSI standards 

— Tables 

— Tasks 

— Terms defined in the text 

— Utilities 

Note that the index entry for a table, figure, or example need only reflect 


the topic or concept that the item addresses. You do not have to use the 
term table, figure, or example in the index entry. 


Create a primary entry for each formal section title only if the section title 
directly applies to the discussion that follows. 


Sometimes, the section title does not accurately reflect the topic discussed 
in that section. Of course, this situation points out a defect in either 

the naming of the section or the way the section is written. However, if 
for some reason the title or the section text cannot be changed, base the 
primary index entry on the topic discussed, not the title. 


Do not create an entry for the subject of the component itself. For example, 
if you are indexing a book about system security, do not use the primary 
entry Security in the index. If the subject, security, needs an entire book 
written about it, a single primary index entry cannot adequately address 
the subject. Use categories of the book’s main topics for the primary 
entries. For example: 


Security auditing 
Security manager 


Security tasks 


Indexing 173 


174 Indexing 


Do not index glossary entries unless the glossary is the only place where 
the terms are used. For example, users may be familiar with a certain 
term used by another computer vendor. Your company may use another 
term for the same concept but include a reference to the other vendor’s 
term in the glossary. In this case, it is appropriate to index the other 
vendor’s term with a cross-refernence to your company’s term. 


Do not index individual error messages. Most information that discusses 
error messages includes an alphabetized list of the messages in an 
appendix. The user has easy access to the information through the table of 
contents and the alphabetical order of the material in the appendix. You 
can use a single primary entry that leads the user to the appendix. For 
example: 


Error messages 
See Appendix C for an alphabetic listing of all error messages 


If the component does not contain a listing of error messages and only one 
or two messages are discussed in the component, evaluate if the material is 
significant. If it is, then you may use an entry such as the following: 

Error messages 


$DBM-Access denied, 5-13 
$DBM-Not ready, 3-6 


In general, use only nouns, noun phrases, or gerunds as primary entries. 
For example: 


Networks 
bringing up nodes on, 6-5 Networks is object of prep. (noun) 
starting, 2-8 Networks is object of verb (noun) 


Do not use adjectives or adverbs alone as primary entries. For example: 
Use 


Local area terminals, 2-3 
Local mode, 3-16 


Do not use 


Local 
area terminals, 2-3 
mode, 3-16 


Avoid using a primary entry as both a noun and an adjective at the same 
time, particularly if doing so breaks up a compound term commonly used 


in the text. For example: 
Use 


Object-oriented code, 2-3, 2-7 
Object protection, 9-14 
Objects, defined, 2-1 


Do not use 
Object 
defined, 2-1 


oriented code, 2-3, 2-7 
protection, 9-14 


In the following example, however, the term network interface is used only 
incidentally in the text, and the use of network as both an adjective and 
noun may be allowable. 


Network 
bringing up nodes on, 6-5 Network is object of preposition (noun) 
interface, 6-3 Network is adjective modifying interface 
starting, 2-8 Network is object of verb (noun) 


Avoid using verb phrases as primary entries. In most cases, index the verb 
under its object. 


Use 
User passwords, changing 


Do not use 


Change user password 
Changing a user password 


However, there may be standard tasks that users expect to be able to 
accomplish with the product. While some users read the table of contents 
to find the task, others may use the index as the main point of entry to 
the information. Therefore, you might index information at the task. For 
example: 


Application databases 

building, 4-37 

defined, 2-3 

server procedures for, 3-12 to 3-17, A-2 
Building 

See also individual entities to be built 
application databases, 4-37 

menu databases, 3-24 

request library files, 2-17 

task group databases, 4-32 
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Do not split compound terms, terms that are consistently used to represent 
a concept in text. 


Use 


Disk protection, 3-14, 3-20 
Disk scavenging, 3-16 


Do not use 
Disk 
protection, 3-14, 3-20 
scavenging, 3-16 
Do not include two topics in one entry. Each topic should have its own 
primary entry. 
Use 
Primary passwords, 5-1 


Secondary passwords, 5-3 


Do not use 


Primary and secondary passwords, 5-1, 5-3 


If you want to show that the two topics are related, you can index them as 
follows: 
Primary passwords 


See also Secondary passwords 
assigning, 5-1 


Secondary passwords 

See also Primary passwords 

assigning, 5-3 
Avoid using more than one primary entry with multiple page numbers for 
the same topic. Place the page numbers with the term used in the text, 
and use a cross-reference to the synonyms for the entry. 


Use 


Flags 
See Qualifiers 


Options 
See Qualifiers 


Qualifiers, 8-1, 8-3, 9-10 


Do not use 

Flags, 8-1, 8-3, 9-10 
Options, 8-1, 8-3, 9-10 
Qualifiers, 8-1, 8-3, 9-10 


The pages on which the information is found are listed in only one place 
in the index — with the entry Qualifiers. Besides reducing the number 
of duplicate page number references, this guideline ensures that the user 
knows what term to look for in the text when looking up the information 
(that is, qualifiers rather than flags or options). 


If there is only one page number associated with a topic, you may include 
the page number with both the topic and the synonym. In this way, the 
user finds the information in one step rather than two steps. However, 
if the synonym is not common, the user may have difficulty finding the 
proper information in the text. 


Create synonym entries for all possible primary entries. 


For a given primary entry, the number of synonym entries you include in 
the index depends on how many ways you think the user might look up 
the topic. For example, if you have a primary entry Qualifiers, you might 
want to include two synonym entries, Flags and Options, to ensure that the 
user finds the information. Use cross-references from the synonyms to the 
primary entry. For example: 
Flags 

See Qualifiers 
Options 

See Qualifiers 


Qualifiers, 5-4, 5-5 to 5-10, 6-13 


Do not automatically index every occurrence of an often-used term. 
Evaluate each occurrence of the word and decide whether a page reference 
in the index is necessary. For example, you are indexing a book about text 
editing, and the word cursor is used many times. Index the significant 
information, such as changing the appearance of the cursor or the different 
ways to move the cursor. Do not index each passing reference to moving 
the cursor. 
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For each entry that is a command, qualifier, parameter, or similar item, 
indicate the type of item in the index entry. 


For example, a certain term may be both a command and an option, 
depending on how it is used. Thus, to avoid confusion, modify the term 
with the correct item name. 


Use 


include command, 9-28 
include option, 10-13 


Do not use 


include 
command, 9-28 
option, 10-13 


If a symbol commonly precedes an item (such as a slash character before 
a qualifier name or a minus sign before an option), it is not necessary 
to include the symbol with the item. For example, -include option may 
be redundant. The word option sufficiently indicates that the term is an 
option. 


Use the complete form of commands, options, and so on. Do not use 
abbreviated forms. 

Use 

SET DEFAULT command 


Do not use 
SET DEF command 


Make primary entries as specific and descriptive as possible. Use a cross- 
reference at the general primary entry (such as ACEs) to refer the user to 
the more specific entry. 


Use 


ACEs 
See Image ACE, Protection ACE, Security alarm ACE 


Image ACE, 3-1, 3-5, 4-16 
Protection ACE, 3-2, 3-7, 4-17 
Security alarm ACE, 3-3, 3-5, 4-13 


Do not use 
ACEs 

image ACE, 3-1, 3-5, 4-16 

protection ACE, 3-2, 3-7, 4-17 

security alarm ACE, 3-3, 3-5, 4-13 
It is best to assume that the user looks up a specific topic (such as 
Protection ACE) more often than a general one (such as ACEs). Therefore, 
creating entries that are as specific as possible prevents the reader from 
going through two entry levels to find information. As in the previous 
example, if the reader does look up the general topic ACEs, the index 
points to the more specific topics. 


However, if there is only one page number associated with each specific 
topic, you may place the page numbers with both the general and specific 
topics. For example: 


ACEs 

image ACE, 3-1 
protection ACE, 3-2 
security alarm ACE, 3-3 


This reduces the number of steps the user takes to find the information. 
In general, index acronyms and abbreviations under the acronym or 
abbreviation. Provide a cross-reference at the full term. For example: 
Use 


Access control lists 
See ACLS 


ACLs, 4-1, 7-3 
Do not use 
Access control lists, 4-1, 7-3 


ACLs 
See Access control lists 


However, if the spelled-out form is more commonly used, index the spelled- 
out form and use a cross-reference at the acronym or abbreviation. 


If an acronym or abbreviation is used in both the index and the glossary, 
use the same form in both places. Do not use the shortened form as the 
main entry in the index and the spelled-out form as the main entry in the 
glossary. 
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Use the plural form for primary entries except where using the plural is 
awkward or misleading. Consistently using the plural form makes index 
correlation and maintenance easier. For example, always using the plural 
form prevents the following error in your index: 


Printer, 5-2 
Printers, 5-2 


laser, 2-3, 5-4 
LOP, 5-3 


However, use the singular form when the plural is incorrect or imprecise. 
For example, some nouns are never used as plurals, such as an abstraction 
like the word clarity. In other cases, using the plural is misleading; if there 
is only one INDEX qualifier to be described, using IMDEX qualifiers is 
clearly wrong. 


Unless a word is in all uppercase or is case sensitive, use an initial capital 


letter for the primary entry in the index. If a primary entry has more than 
one word, use an initial capital letter only for the first word unless the 
term is a proper noun. For example: 


Use 


Distributed File System, 3-3 (proper noun) 
Mail utility commands, 5-4 


Do not use 


Distributed file system, 3-3 (proper noun) 
Mail utility commands, 5-4 


Index symbols both as symbols, at the beginning of the index, and under 
the name of the symbol. For example: 

& (ampersand), 3-9 

A 

Ambiguity, deleting, 1-6, 4-11 

Ampersand (&), 3-9 

Articles, 3-2 

If the text formatting tool cannot place symbols at the beginning of the 
index, index the symbols under their names. . 


Place numeric primary entries before the alphabetic entries if the text- 
formatting tool allows it. For example, the primary entry 64-bit should 


go before any of the alphabetic entries, as follows: 
64-bit, 5-12 


A 
Access control, 1-5 
Application generators, 2-6, 2-9, 2-10 


Put all numeric entries in ascending numeric order. For example: 


070R disk, 1-1 
32-bit, 1-1 
64-bit, 1-2 


If the formatting tool cannot place numeric entries before alphabetic 
entries, then treat the numeric entries as if the numbers were spelled out. 
For example: 


Phrase Alphabetize as: 
070R disk Zero seven zero R 
32-bit Thirty-two bit 

1957 (the year) Nineteen fifty-seven 


10.3.3.2 Creating Secondary Entries 
Use the following guidelines when creating secondary index entries: 


Use verbs, verb phrases, adjectives, nouns, or prepositional phrases. 
For example: 


Terminals 

described, 2-2 (verb) 

in a network, 4-2 (prepositional phrase) 
remote, 3-3 (adjective) 

turning on, 2-3 (verb phrase) 

types, 2-1 (noun) 


If a primary entry has more than three page references, always create a 
secondary entry for each page reference. Otherwise, the user must look up 
each page to find the information. In contrast, the secondary entries tell 
the user immediately which page contains the needed information. 
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Note that The Chicago Manual of Style allows up to five page references 
without secondary entries. However, computer users look to the index for 
quick access to information for accomplishing a task. To accommodate that 
need, it is best to limit the number of page references to three. 


Use 


Terminals 
bit-mapped, 63 
described, 12, 35 
local, 23 
remote, 34 


Do not use 
Terminals, 12, 23, 34, 35, 63 


For similar or related primary entries, index the secondary entries in the 
same way. For example: 


Use 

QUOTE command WRITE command 
described described 
example example 

Do not use 

QUOTE command WRITE command 
described discussed 
example overview 


use of 


Generally, if similar items are treated in the same way in the text, they 
should also be indexed in the same way. However, nonparallel construction, 
as in the previous example, may not always be the fault of the indexer. 
Instead, it may indicate a problem with the structure of the text. 


Use prepositions, articles, and conjunctions judiciously in secondary 
entries. Use them when they make the secondary entries easier to 
understand, but omit them when they do not add meaning to the entry. 


For example, using the preposition of in the secondary entry does nothing 
to enhance the meaning of the primary entry: 


Use 


Authorizing system use 
overview 


Do not use 


Authorizing system use 
overview of 


In the following example, however, the preposition fo clarifies the meaning 
of the primary entry: 


Use 


Data erasing 
to protect disks 


Do not use 


Data erasing 
protect disks 


If the preposition were omitted, the user may assume that data erasing is 
something to protect disks from, instead of something to protect disks with. 


Do not put long lists of similar items under a primary entry. Instead, make 
each item a primary entry of its own. 

Use 

Batch mode, 6-1 

Dialup mode, 6-2 

Interactive mode, 6-2 


Login modes 
See also individual login type entries 
types, 6-1 to 6-3 


Do not use 


Login modes 
batch mode, 6-1 
dialup mode, 6-2 
interactive mode, 6-2 


The index is not the place to give the user technical information such as a 
list of which login modes are available. An index entry such as Login mode 


merely points the reader to the place in the text where the various login 
modes are identified. 


If a term has lowercase letters in text, do not capitalize the term in the 
secondary entry. For example: 
Use 


Variables, 3-4, 3-9 
hyphenating, 3-7 
italicizing, 3-4 
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Do not use 
Variables, 3-4, 3-9 


Hyphenating, 3-7 
Italicizing, 3-4 


e Ifa primary entry has only one secondary entry, combine the two into a 
primary entry. For example: 


Use 


Logarithmic scaling, 5-3 
Logins from remote terminals, 4-2 
Lookup values, 9-13 


Do not use 


Logarithmic scaling, 5-3 
Logins 

from remote terminals 4-2 
Lookup values, 9-13 


¢ Limit the use of tertiary entries. In a few cases, tertiary index entries may 
be justified, but in most cases they are not necessary. 


Use 


Logins 

alternate command procedure, 2-20 

controlling number of dialup attempts, 11-9 
dialup, 11-8 

failures, counting for break-in detection, 11-10 


Do not use 


Logins 
alternate command procedure, 2-20 
dialup, 11-8 

controlling number of attempts, 11-9 
failures 
counting for break-in detection, 11-10 


e If multiple secondary entries refer to the same hardcopy page, you may 
combine the entries into a single, more general secondary entry. 


Use 


Printers 
operating, 8-2 
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Do not use 


Printers 
configuring, 8-2 
installing, 8-2 
maintaining, 8-2 


However, in indexes for online books, such consolidation may not be useful. 
Indexes in online books do not include page numbers. Therefore the user 
does not necessarily know that all the references are to the same page. If 
the user is unfamiliar with the material, a consolidated secondary entry 
may not give enough information to signal that the user has found the 
correct index entry. 


10.3.3.3 Using Cross-References 
Cross-references are important for two reasons: 


Using See entries helps you to avoid indexing the same topic and its page 
numbers under many primary entries. This reduces the size of your overall 
index and ensures that it is as concise as possible. 


Using See also entries ensures that the user can access information on 
related topics. 


Use the following general guidelines when using index cross-references: 


Index cross-references do not have any page numbers associated with them. 
For example: 


Use 


Security problems, 1-2 
See also Networks 


Do not use 


Security problems, 1-2 
See also Networks, 3-6 


Make sure that a cross-reference loop is not circular and that it points to 
an actual primary entry. For example: 


Use 


Terminals 
See Peripherals 


Peripherals, 1-5 
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Do not use 


Terminals 
See Peripherals 


Peripherals 
See Printers, Tape drives, Terminals 


e Italicize the words See and See also in index cross-references. Do not 
italicize the cross-referenced terms. 


Use 


File protection 
See Object protection 


Do not use 


File protection 
See Object Protection 


File protection 
See Object Protection 


However, if the cross-referenced term is already in italics, use the regular 
typeface for the cross-reference. For example: 
Use 


Choose, 2-20 
See also Enter 


Do not use 
Choose, 2-20 
See also Enter 
Use the following guidelines when using See cross-references: 
e Use a See cross-reference only when the primary entry has no secondary 
entries. For example: 
Use 


Printers 
configuring, 4-1 
installing, 4-2 
monitoring, 4-3 


Printing devices 
See Printers 
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Do not use 
Printers, 4-1 to 4-3 


Printing devices 
See Printers 
configuring, 4-1 
installing, 4-2 
monitoring, 4-3 


Use a See cross-reference to point from one primary entry to a preferred 
primary entry. 
Use 


Alarm ACE 
See Security alarm ACE 


Security alarm ACE, 6-3 


Do not use 
Alarm ACE, 6-3 

Security alarm ACE, 6-3 
Use a See cross-reference to point from a general primary entry to a more 
specific primary entry or entries. 
Use 

Backup Utility, 4-4, 7-2 
Error Logging Utility, 8-4 
Mount Utility, 9-5 

Utilities 

See Backup Utility 


See Error Logging Utility 
See Mount Utility 


Do not use 

Utilities 
Backup Utility, 4-4, 7-2 
Error Logging Utility, 8-4 
Mount Utility, 9-5 


You may use up to three See cross-references for one primary entry. For 
example: 


ACEs 
See Image ACE, Protection ACE, Security Alarm ACE 
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However, if there are more than three cross-references, it is better to 
handle the entries with a See also cross-reference. For example: 


Use 


ACEs 
See also specific ACE types 
types, 6-1 to 6-3 


Identifier ACE, 6-3, 6-10 to 6-12 
Image ACE, 6-1, 6-5 

Protection ACE, 6-2, 6-7 
Security Alarm ACE, 6-2, 6-9 


Do not use 


ACEs 
See Identifier ACE, Image ACE, Protection ACE, 
Security Alarm ACE 


Use the following guidelines when using See also cross-references: 
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Use a See also cross-reference to point from one primary entry to another 
primary entry containing related information. 


For example: 


Security problems 
See also Networks 
categories, 1-2 
identifying, 3-9 


Do not use a See also cross-reference if the related information to which 
the cross-reference points is already mentioned in the the original entry. 


For example, a discussion of printers extends over two pages, and related 
information about paper appears on the second page of the printers 
discussion. In this case, you do not need to refer to the related information 
on paper because the user sees the information on paper while reading the 
discussion on printers. 


Use 
Paper, 3-3 
Printers, 3-2 to 3-3 


Do not use 
Paper, 3-3 


Printers, 3-2 to 3-3 
See also Paper 


10.4 Master Indexes 


Information sets often include a master index, an index that points to topics 
across an information set. Index entries contain the title of the book to which 
they belong as well as the page number within the book. The titles are usually 
abbreviations of the complete titles; a key to the titles precedes the master 
index. For example: 


Master Index 
Key to Book Titles: 


APPDEV Introduction to Application Development 
DBINTR Introduction to DECproduct 

DBGDMP Guide to Database Management and Performance 
DBGDD Guide to Database Design and Definition 


Application design 
data design, APPDEV 2-6 to 2-9, DBINTR 2-3, DBGDD 3-9 to 3-15 
performance, APPDEV 6-18, DBINTR 6-18, DBGDMP, 7-3 to 7-14 
Areas 
adding pages, DBGDMP 5-6 
enlarging CALC range, DBGDMP 5-10 
size, DBGDD 3-11, DBGDMP 5-5 


You generally use the same process and principles in creating a master index 
as for a single-book index. However, the following guidelines are particularly 
important in developing master indexes: 


e As a team, decide on the title abbreviations to be used in the master index 
and how you will define those for the users. 


° Use consistent spelling and capitalization for all index entries throughout 
the information set. Otherwise, the master index has a different entry for 
each variant form. 


Indexing 189 


190 


Indexing 


Establish consistent terminology to be used across all index entries. For 
example, avoid the following type of inconsistency: 


Areas 
defined, DBGDMP 5-1 
definition, DBGDD, 3-3 


Establish conventions for adding qualifying words to primary entries to 
avoid ambiguous entries and duplicate entries. For example: 

Use 

DELETE command 

DELETE routine 


Do not use 


DELETE ==> Ambiguous entry. Is this the same as the Delete command? 
If not, what does this entry refer to? 
DELETE command 


Establishing such conventions is particularly important for: 
— Commands 

— Data types 

— Protocols 

— Routines 

— Scripts 

— Services 

— Utilities 


Use the plural form for primary entries, except where the plural is 
awkward or misleading. Discuss exceptions among the team so that entries 
are consistent across all the components. 


As a team, decide on the major topics in the information set and which 
topics will be treated as primary entries in the master index. Consolidate 
other topics as secondary entries under the primary entries. For example, 
include important terms used throughout the information set as primary 
entries. Make related but less frequently used terms into secondary 
entries. If you must use related terms as primary entries, include See also 
cross-references under both the major topic and the related terms. In the 
following example, the term Client/server communications is a major topic 
in the information set, but the concept of server pools is also important and 
has its own primary entry. The master index uses See also cross-references 


at both entries. The master index directs users who look up either Clients 
or Server instances to the main topic of Client / server communications. 


Clients 
See Client/server communications 


Client/server communications 
See also Server pool 
Clients, APG 2-3, APG 2-13, APR 1-10 
Server instances, APG 4-5, APR 3-15, APR 3-23 


Server instances 
See Client/server communications 


Server pool 
See also Client/server communications 


e As a team, decide whether to index arguments, options, parameters, and 
so on in the master index. The size and complexity of the product may 
influence your group’s practice. 


e Include See and See also cross-references in all single-book indexes 
where they apply. Otherwise, the master index will contain the correct 
cross-references, but the single-book indexes will be incomplete. 


10.5 Editing an Index 


Editing an index is the process of shaping individual entries into a coherent 
whole. You delete, consolidate, and correlate the draft index entries. 


If you have done a thorough job of identifying pertinent information, selecting 
appropriate index entries, and maintaining a reasonable degree of consistency, 
the editing process should be relatively painless. If you have not, the editing 
process establishes consistency in your index entries but might not produce a 
useful index. 


Begin by reviewing the most significant topics for the material, which generally 
have many secondary entries. The edits you make to these entries affect the 
rest of the index entries. After revising the significant topics, edit the other 
entries, starting at the beginning of the alphabet and working through to the 
end. 
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Use the following guidelines when editing each topic and the overall index: 
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Do all entries merge properly? You may need to correct capitalization or 
change a singular form to a plural form. 


Do the primary and secondary entries make sense in the context of the 
index? Will the user be able to work back from the index entry to the 
proper section in the text? 


Are all possible synonyms covered? Have all entries been permuted that 
could be permuted? Some permutations will not make sense or be that 
helpful, so use your judgment. 


Are the page numbers for permuted entries the same? 


Can some secondary entries be consolidated? If more than half the 
secondary entries for one primary entry come from one page or the same 
two or three pages, consider combining or omitting some of them. 


Are there redundant secondary entries? Some duplicate secondary entries 
are helpful if they are not next to each other and there are at least six 
other secondary entries. However, duplicate entries that are the result of 
slightly different wording (creating and creation of, for example) are not 
helpful. 


Do some of the secondary entries need to be reworded because of the way 
they are alphabetized? Occasionally, prepositions, conjunctions, and the 
like that improve the sense of the secondary entry affect the alphabetic 
order. You may need to reword the secondary entry so that the key words 
in the secondary entry are first, not the preposition or conjunction. For 
example, you may need to make the following type of change: 


Vertical lists Vertical lists 
with em dashes, 2-79 ===> em dashes with, 2-79 
with periods, 2-78 periods with, 2-78 


Is there sufficient cross-referencing? 


Do the cross-references exist? Do not direct the user to a topic that does 
not appear in the index. 


Are the See also cross-references meaningful? If there are only one or two 
page references at the cross-referenced entry, the cross-reference may not 
be that useful. 
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Online Information 


Online information is any information in text or graphic 
form that users can display on their workstation or terminal 
screens. Online information can take several forms: 


¢ Context-sensitive information built into the user interface 


e Different types of reference material 


e Training modules and computer-based instruction 
¢ Books 


Online information gives users quick and efficient access to a library of 
technical information right at their desks. In addition, online information 
eliminates the need for large amounts of storage space for hardcopy documents. 
Thousands of pages can be stored on disk or CD-ROM. 


This chapter discusses the following forms of online information that are 
currently available to Digital customers. These types of information are the 
most common forms of online information supplied to customers, though they 
are not the only types. (For example, customers may access their own DDIF 
and POSTSCRIPT files using the CDA™ Viewer. In some cases, they can access 
the product installation guides from the software CD-ROM.) 


¢ Online books (using the DECwindows Bookreader application) 
(Section 11.1) 


e Online help (Section 11.2) 
— DECwindows XUI™ Help (Section 11.2.1) 
— DECwindows Motif® Help (Section 11.2.2) 
— OpenVMS Help (Section 11.2.3) 


— Reference pages (manpages) for systems based on the UNIX® operating 
system (Section 11.2.4) 


Section 11.3 briefly discusses hypermedia technology. 
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11.1 Online Books 


11.1.1 


Books may be available in both hardcopy and online form or online form only. 
Online books are stored on a CD-ROM and viewed on a workstation or 
terminal. Online books are accessible to multiple users simultaneously, as long 
as they have the appropriate display device. This availability eliminates the 
problem of multiple users needing multiple copies of the same book. 


See Section 6.10.1 and Section A.3 for information on reviewing the quality of 
online books. 


Bookreader Features 


The Bookreader application is one model that gives users access to the online 
versions of books. Using the DECwindows graphical user interface, users 
browse through the book’s table of contents and index and click on specific 
topics. The Bookreader application displays the information in another 
window. Users can also activate hotspots within the book to call up other 
related information. (See Section 11.1.2.2 for more information on hotspots.) 


Some of the features of Bookreader include: 

e Ability to display multiple windows and books 
e Integrated text and graphics 

¢ Scroll bars for scanning text 

e Automated cross-referencing within a book 

¢ Customizable library of books and bookshelves 
¢ Online help 

Figure 11—1 shows a sample Bookreader display. 
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Figure 11-1 Sample Bookreader Display 


Title Page 
Copyright Page 
> 1 Bookreader 
> Figures 
> Index 


SRS 


Se 


11.1.2 Bookreader Concepts 


Although an online book generally contains the same information as its 
hardcopy equivalent, there are some concepts specific to Bookreader that may 
affect the conventions you use in creating your source files. No matter what 
authoring tool you use, your book must have a table of contents and an index 
for Bookreader; otherwise, the user must go through the book topic by topic. 
See Section B.9.2 for further information on formatting books for Bookreader. 
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11.1.2.1 


The following sections describe: 

¢ Information chunks and topics (Section 11.1.2.1) 
¢ Hotspots (Section 11.1.2.2) 

¢ Pop-up windows (Section 11.1.2.3) 


Information Chunks and Topics 


A chunk of online information is the smallest unit of information that 
Bookreader can access from the table of contents, the index, or other sections 
that refer to them. A topic consists of one or more information chunks 
displayed on successive screens. Topics appear in the table of contents. 


Bookreader cannot go directly to a line in a paragraph from an index entry or 
cross-reference. Instead, Bookreader accesses the whole chunk that the user 
references. If the chunk of information that the user selects is larger than 
the text window, the user must use the vertical scroll bar to read all the text. 
Therefore, information is more accessible if you create smaller online chunks 
and topics to fit onto the screen. 


In general, a topic should not be shorter than one quarter of a screen nor longer 
than five screens. Also consider that text may expand up to 25 percent when it 
is translated. Therefore, a topic that is of suitable length in the original may 
be too long after translation. 


The concept of optimal online topic size is closely related to the concept of 
modular information. See Section 4.1 for more information on modularity. 


Typically, chunks of information include: 

¢ Chapters 

e Sections 

e Formal figures, tables, and examples 

¢ Template sections and subsections 

¢ Footnotes, glossary terms, and messages 
¢ Paragraphs and lists 

¢ Definition list items 

¢ Copyright page elements 

e Title page elements 


Depending on the authoring tool you use, you can control the size of online 
chunks and topics. See Section B.9.2 for more information. 
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11.1.2.2 Hotspots 


11.1.2.3 


A hotspot is a region within the window that the user activates with the 
mouse to display cross-referenced material. For example, if the user clicks on 
a reference to a figure, the figure is displayed in a separate window, known 
as a pop-up window. (See Section 11.1.2.3 for more information on pop-up 
windows.) 


Cross-references to other sections of text are also hotspots, except that the 
referenced topic replaces the current text in the window. For example, if 
the user clicks on a cross-reference to another chapter or section, that topic 
replaces the current material in the topic window. (Users may be able to 
control whether a new topic replaces the current topic or is displayed in 
another window.) 


Hotspots are easily distinguished by the box around them: 
See for an example of the main menu screen. 


Users can control whether the box is always visible or visible only when they 
move the mouse over the hotspot. 


Pop-Up Windows 

A pop-up window displays referenced material, usually a formal figure, table, 
or example. The pop-up window is sized to fit the material it contains; it 
overlays any text that is currently on the screen. The user displays the pop-up 
window by using the mouse pointer to activate a hotspot in the online text or 
by clicking on a formal table, figure, or example in the table of contents. 


Bookreader puts all formal tables, formal examples, formal figures, and 
footnotes in pop-up windows. All informal tables, examples, and figures appear 
in the main body of the text; they do not have captions or symbolic names, and 
they do not appear in the table of contents. Depending on the authoring tool 
you use, you can format your file to put that information in a pop-up window. 
For example, you might put an informal example in a pop-up window if it is 
long or wider than 33 picas. The user clicks on the hotspot to see the pop-up 
window for the informal example. 


FIGURE: Click here to display figure. 


Do not use a pop-up window for an informal table, figure, or example if it fits 
easily in the topic window. See Section B.9.2 for information on using the 
VAX DOCUMENT authoring tool to control the information that appears in 
pop-up windows. 
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11.1.3 Indexing Online Books 


The table of contents and the index are the users’ primary tools for finding 
information in and navigating through online books. Therefore, the 
completeness, accuracy, consistency, and balance of the index are crucial 

to the users’ ability to access the online information. Section 10.3 contains 
general guidelines for creating any index, no matter what the output media. 


In addition, for online books you must: 


Place index entries after the section titles; that is, make sure the index 
entry is embedded within the appropriate section, not before placed before 
it. 


Make sure that each primary entry in the index has a hotspot around it 
unless the entry also has secondary entries. 


11.2 Online Help 


Digital currently uses four major online help technologies: 
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DECwindows XUI Help (Section 11.2.1) 
DECwindows Motif Help (Section 11.2.2) 
OpenVMS Help screens (also known as DCL Help) (Section 11.2.3) 


Reference pages for systems based on the UNIX operating system 
(Section 11.2.4) 


Each type of help provides the user with online information about specific 
tasks, applications, commands, fields, or objects on the screen. 


For whichever type of help you create, use the following general guidelines: 


Make the text brief. If possible, fit a topic within the application’s default 
help screen so that users do not have to use excessive scrolling. 


Use simple, direct language. | 
Avoid an overly friendly or telegraphic writing style. 
Give sufficient information so that users can perform the task. 


Create a visual format that is easy to read. For example, break long 
paragraphs into several shorter ones. 


Reduce text density by using blank lines to separate paragraphs and list 
items. 
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11.2.1 DECwindows XUI Help 


DECwindows applications provide online help that describes application tasks, 
supplements the information available in the books (hardcopy or online), and 
summarizes the information available in the books. 


Some applications also provide context-sensitive help. In these instances, 
DECwindows displays help that is relevant to the objects on the user’s screen. 
It is recommended that applications give context-sensitive help for: 


e Menus 

¢ Menu items 

¢ Dialog boxes (and each component of a dialog box) 
¢ Other objects, such as buttons 


The source files for DECwindows help screens are ASCII files. Because the 
DECwindows help libraries are hierarchical, you use key numbers to indicate 
the level in the hierarchy. For example, the help describing the File menu 
might be structured as follows: 


1 Menus 
[text describing menus... ] 


2 File menu 
The File menu is... 


3 Open 
When you choose Open from the File menu... 


3 Close 
When you choose Close from the File menu... 


However, with DECwindows XUI help, you can expand beyond a strictly 
hierarchical structure. Using the =INCLUDE command, you can connect 
DECwindows help screens to any topic, regardless of the topic’s physical 
location in the library. For example, if your help library has a level-2 topic 
on printing files under the overview topic and another topic under menus 
describing the File menu, you can list the File menu topic as an additional 
topic to the discussion of printing files: 


1 Overview 
[text describing the product... ] 


2 Printing Files 
=INCLUDE Menus File menu 
To print FOO files... 


3 Remote printers 
[text describing remote printers... ] 
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1 Menus 
[text describing menus... ] 


2 File menu 
To print, save, or restore FOO files... 


In addition to the general guidelines for creating help, use the following 
guidelines when creating DECwindows XUI help: 


¢ If possible, limit the length of each topic to 18 lines so that the help text 
fits within the default help screen size. 


¢ ‘To allow for the indenting of help text, limit the length of each line to 55 
characters. Your text formatting tool may automatically format the text for 
you. 


¢ Include a task-oriented topic for each feature of the application. 
e Use task-oriented words that users can easily relate to the user interface. 


¢ Describe application features in the order in which they are displayed on 
the screen. 


¢ Include context-sensitive topics for each menu, menu item, button, and 
dialog box of the application. 


11.2.2 DECwindows Motif Help 


The DECwindows Motif Help System is a help utility available on a variety 
of Digital’s Motif platforms. Table 11-1 summarizes the availability of 
DECwindows Motif Help on the platforms as of July 1992. 


Table 11-1 DECwindows Motif Help Platforms 


Motif Platform Help Availability 

VMS™ DECwindows Motif Version 1.1 Packaged in base platform 
VMS DECwindows Version 2.0 Packaged in base platform 
mere Worksystem Software™ Version Packaged in base platform 


ULTRIX Worksystem Software Version Not available’ 
4.2 or lower 


DEC™ OSF/1® for RISC Version 1.0 Not available 


1 An installable Bookreader kit began shipping on the ULTRIX online documentation CD-ROM 
bee ati in June 1992. This kit can be installed on a UWS Version 4.2 system to make Help 
available. 


(continued on next page) 
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Table 11-1 (Cont.) DECwindows Motif Help Platforms 
Motif Platform Help Availability 
SUN® Motif Not available 


The main difference between the DECwindows XUI Help System and the 
DECwindows Motif Help System is that the DECwindows Motif Help System 
uses Bookreader (Version 3.0) as the display mechanism for online help. 


Applications converting from the DECwindows XUI Help System to the 
DECwindows Motif Help System will realize the following immediate 
advantages without any extra effort on the part of the writer except for 
the conversion: 


¢ Improved legibility of text (through different fonts and point sizes) 
e Scalability (with no performance penalty for large libraries) 


e A help text look and feel that is similar to the look and feel of the 
Bookreader books 


¢ For writers using the VAX DOCUMENT authoring tool, the ability to use 
the same tags in the help text that are used in the books 


Writers can also take advantage of the following added features for the 
DECwindows Motif Help System files: 


e Graphics capabilities 
e Hotspots 
e Tables 


A primary advantage of the DECwindows Motif Help System over the 
DECwindows XUI Help System is that users can create LinkWorks™ links 
between online help and other pieces of information, such as mail messages, 
Cardfiler cards, and other Bookreader topics. 


Figure 11-2 shows a sample help text as it appears using the DECwindows 
XUI Help System and the DECwindows Motif Help System. 
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migure 11-2 Help Text from the DECwindows XUI Help System and the DECwindows 
Motif Help System 


DECwindows XUI Help System DECwindows Motif Help System 


LinkWorks Support Proportional Fonts 


Overview of the Puzzle a Overview of the Puzzle Bent Lee eR 


Puzzle is a video version of a number puzzle with 


movable squares. The object is to arrange the numbered Overview of the Puzzle 
squares in ascending order using the fewest possible 


moves. Puzzle keeps track of the number of moves Puzzle is a video version of a number puzzle with movable 
you make and displays that number when you solve the The object is to arr: e then bered sqi Si 
puzzle. squ Fa * B . 

ascending order using the fewest possible moves. Puzzle 
Click mouse button 1 (MB1) on the square you want to keeps track of the number of moves you make and displays 


move. You can only move the squares that are adjacent that number when you solve the puzzle. 
to the blank square; however, it is possible to slide 


an entire row at a time. 


Click mouse button 1 (MB2) on the square you want to move. 
For information about using Puzzle, double click on an You can only move the squares that are adjacent to the blank 
item from the list of additional topics below. square; however, it is possible to slide an entire row at a time. 


For information about using help, choose Using Help 
from the Help menu above. 


For information about using Puzzle, click on an item from 
the list of additional topics below. 


Additional Topics: 
DECwindows Basics 
Starting a New Game 
Changing the Puzzle Settings 
Quitting a Puzzle Session 
Puzzle Menus 


DECwindows Basics 

Starting a New Game 
Changing the Puzzle Settings 
Quitting a Puzzle Session 


Puzzle Menus 


Additional topics included 
in same window 


11.2.3 OpenVMS Help 


OpenVMS Help screens are ASCII files that are organized into library form by 
the OpenVMS Librarian Utility. The help screens display a brief summary of 
key information. The information may be a summary of topics for new users, 
overview information about a product, or command formats and qualifiers for a 
particular product. 


OpenVMS applications also provide online help within the application. 
This form of online help is application specific and is usually a summary 
of information that is in the information set. However, as more information 
moves on line, the help system may be the source of most information on 
low-level tasks or on reference information. 
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To create the online help, writers create an ASCII file with the help text and 
use the LIBRARY command to insert the new help modules into the help 
library. To revise help modules, writers extract help modules from the help 
library files, edit the help modules in ASCII form, and then use the LIBRARY 
command to replace the help modules. See the Librarian Utility documentation 
for more information. (How writers create the ASCII help modules depends 

on the tools they use. For example, some tools let writers use the same 
documentation source files for both the help modules and books. To produce 
the help modules, the writers process the documentation source files with 
special format codes.) 


Help topics are arranged hierarchically. Level 1 topics are what users see when 
they enter HELP at the system prompt. Level 2 topics are automatically listed 
under the heading "Additional information available" of Level 1 topics. For 
example, the help topics in one module might have the following hierarchical 
arrangment, where the numbers in the left margin indicate the position of the 


topic in the hierarchy: 


2 CORRELATE SET_Options 


DIRECTORY SUBMIT 


In addition to following the principles of writing clear, concise material, writers 
need to use the following guidelines when writing OpenVMS help modules. 
Your text formatting tool may automatically provide the proper spacing, 
margins, and topic title format. 


e Always reserve the first column of the file for the level number (the topic’s 
position in the hierarchy). The Librarian Utility interprets any number 
in column 1 as a level number and interprets the first word following the 
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number as the title for the help module. To avoid problems, do not put any 
text in column 1. 


e Be aware of the width of text. The Librarian Utility indents three spaces 
for each level of topic below Level 1. Setting a right margin of 65, for 
example, is sufficient for up to 4 levels of help topics. 


¢ Use an underscore to connect the words in multiword topic titles (for 
example, SET_Options). 


¢ The default length of a level-1 keyword (topic title) is 15 characters. 
However, you can use up to a maximum of 128 characters for a keyword. 
See the Librarian Utility documentation for more information on signalling 
keyword length in the LIBRARY command. 


Example 11-1 shows a sample OpenVMS Help module. 


Example 11-1 Sample OpenVMS Help Module 


1 New_Keywords 
There are three new keywords in this version of DECproduct: 


Oo CORRELATE 
o DCL_Commands 
oO SET Options 


2 DCL Commands 
The DCL Commands keyword lets return to system level to perform 
different functions. 


3 DIRECTORY 
DIRECTORY lets you display the files in your default directory. 


3 MAIL 
MAIL invokes the MAIL utility. 


3 SUBMIT 
SUBMIT lets you submit a job for batch processing. 


4 Examples 
If you want to test the module you have just created, use the 
SUBMIT keyword. You can use any of the qualifiers you normally 
use with the /BATCH qualifier. 


DECproduct> DCL Commands 
DECproduct> SUBMIT modulel /notify/queue=my$batchq 
DECproduct> 
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11.2.4 Reference Pages 


Reference pages form the online help for systems derived from the UNIX 
operating system. These pages are often called manpages because you use the 
man command to access the information. There is a reference page for each 
command, system call, subroutine, special file, utility, and procedure. The 
reference pages are divided into eight sections: 


Section 1 Commands 
Section 2 System Calls 
Section 3 Library Routines 


Section 4 File Formats 
Section 5 Macro Packages and Language Conventions 
Section 6 Games 


Section 7 Special Files 


Section 8 System Maintenance Commands and Procedures 


Note that Sections 4, 5, and 7 sometimes differ among the various UNIX 
operating systems. For example, Section 4 on the ULTRIX operating system 
contains reference pages for special files; on OSF/1 operating systems, special 
files are documented in Section 7. 


When you create a reference page, you need to determine in which section 
the page belongs. Some sections, particularly Section 3, have a number of 
subsections to make it easier for users to find information. Often, large 
applications have separate subsections for their reference pages within the 
major divisions. For example, the ULTRIX/SQL software has reference pages 
in Section 1sql and in Section 8sql. 


The source files for reference pages are coded in nroff, an ASCII text formatter 
available on nearly all UNIX operating systems. The format instructions 

you use for nroff are known as the man macro package. A macro package 
consists of format instructions and definitions that specify the output for each 
instruction. 


Many UNIX operating systems ship source files for reference pages. When a 
user invokes the man command for a particular page, the system formats the 
page and displays the output on the terminal. Some systems, however, ship 
preformatted reference pages that do not require dynamic formatting each time 
a user wants to view a page. 
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Reference pages contain a number of standard elements and some optional 
ones. The names and order of the elements differ somewhat among UNIX 
operating systems, but three elements appear in all references pages: 


e Name 
¢ Description 
¢ Related Information 


The following list shows the element names and order for OSF/1 command 
reference pages: 


¢ Name 
e Synopsis 
¢ Flags 


¢ Descriptions 

e Subcommands 

e Examples 

e Files 

¢ Notes 

e Cautions 

¢ Diagnostics 

e Exit Values 

¢ Related Information 


Often, online reference pages are printed and serve as the reference 
information for the operating system as well as for applications and products 
that run on the operating system. Reference pages are also available through 
the Bookreader. The composite of the operating system reference pages is 
sometimes referred to as the UNIX Programmer’s Manual in text books 
discussing UNIX operating systems. 


11.3 Hypermedia 


Hypermedia is a relatively new type of information technology. In the 

ideal system, users access a range of information in different formats, from 
traditional text and graphics to full color animated videos with sound. The 
information sources are diverse; users might create connections between online 
books, mail messages, electronic conferences, and online training. 
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Traditionally, users access online information linearly, in a top-to-bottom, 
front-to-back fashion. Hypermedia technology supports a nonlinear use of 
information through networks of connected information. In the ideal system, 
users establish their own connections between modules and set up their own 
criteria for accessing and sharing information. 


Digital currently gives users hypermedia capabilities in several ways: 


e Users can navigate Bookreader books in a nonlinear way through the use 
of hotspots and by accessing topics from the table of contents and index. 
See Section 11.1.2.2 for information on hotspots in Bookreader books. 


Users can also use hotspots in DECwindows Motif Help. 


e LinkWorks is a DECwindows application that gives users the ability 
to create links between information that is stored and accessed by 
DECwindows desktop applications. For example, a user can link a 
DECwindows mail message with a DECwindows Calendar timeslot. A user 
can also make links between Bookreader topics, Calendar timeslots, and 
Cardfiler cards. 


As with any new technology, there is continued testing and debate about 

the best uses of hypermedia. (In fact, the exact meanings of the terms 
hypertext, hypermedia, and hyperinformation are open.) In a recent article 
(see Section B.9), William Horton suggests that, to be most useful, hypermedia 
systems need to be used in combination with other types of online information 
methods (such as context-sensitive information and menus of topics), the 
combination depending on the type of information being presented. There are 
also debates about using predetermined information paths and limiting access 
to certain modules. 


As the technology develops, what is clear is that hypermedia will have a 
significant impact on the preparation and presentation of online information. 
Information designers will need to think in terms of discrete modules that 
can be used in a variety of contexts. They will need to rethink traditional 
structures, transitions, and cross-referencing techniques. In addition, the 
heterogeneous formats of the information will require an understanding not 
only of text and static graphics but also of voice, video, and animation. All 
these changes will affect how information designers work, the types of skills 
needed to create and produce information, and even the structure of the 
information team. 
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12 


Using Navigational Cues 


Navigational cues are structural or design elements that 
help users find information quickly and easily. Navigational 
cues also help users understand the structural context of 
the information, helping them understand the relationship 
among different parts of an information component or 
information set. 


As noted in a recent article on access aids (see Mackh 

and Rew, Section B.2), consistency is the key to the effective use of navigational 
cues. Once you establish a convention, you set users’ expectations about the 
meaning of the element; inconsistent use confuses users rather than helps 
them. For example, if you use boldface type to introduce terms defined in text, 
use that convention throughout the component. 


The following sections discuss both structural elements (Section 12.1) and 
design elements (Section 12.2) that you can use to help users find the 
information they need. 


12.1 Structural Cues 


Structural cues are explicit pointers to the organization and content of the 
material. Structural cues include the following elements: 


e Tables of contents and titles 


The table of contents and index are the two main ways that users find 
the information they need within a book. The table of contents lists 

all the parts, chapter and appendix titles, and section titles in a book, 
including the glossary and index. The table of contents should also include 
separate lists of figures, tables, and examples. In hardcopy books, the 
table of contents also lists the starting page numbers for each element 
(except parts). In online books, users click on the appropriate element 

in the table of contents; the element is then displayed in a topic window. 
(See Section 11.1.1 and Section B.9.2 for more information on using the 
Bookreader application.) 


Using Navigational Cues 209 


For hardcopy books, you may also include a separate table of contents 

for different sections of a book. For example, you may list the contents 

of a reference section on a part page or tabbed divider that introduces 

the section. Some books list first-level section titles in the book table of 
contents and then list the full contents of each chapter in separate chapter 
tables of contents. However, note that this approach is not effective for 
online books because users cannot access all topics from the main table of 
contents. 


For both hardcopy and online information, make sure that the titles listed 
in the table of contents exactly match the titles in the text. Also make sure 
that each title clearly reflects the contents of its accompanying section, 
figure, table, or example. The titles, both in the table of contents and in 
the text itself, are the users’ cues to the contents of each section. 


See The Digital Style Guide for details on the placement and format of 
tables of contents and for guidelines on choosing effective titles. 


Because you can create hotspots in online help topics with the 
DECwindows Motif Help System, you can create a mock table of contents 
that lists all the major tasks of the application. You can include this 
contents listing as an additional topic in appropriate help topics (such as 
the On Window or On Version help topic or a Getting Started topic) so that 
users have a home base to return to when they are not sure where to go 
next. Users can then click on the task in this contents list to get to the 
help topic they need. 


e Indexes 


An index is the other primary way that users find the information they 
need. The index is an alphabetical listing of the topics and subtopics 
discussed in the book. (With the DECwindows Motif Help System, you 
also provide an index to the online help for an application.) As Chapter 10 
describes, indexes provide multiple points of entry to topics by listing 
synonyms and cross-references to related topics. 


See Chapter 10 for guidelines on creating effective indexes. 


e Overviews 


Topic overviews are another way of introducing users to the material 
discussed in a part or chapter. An overview may be as simple as a list of 
the topics, as in the overview included with Part II. An overview may also 
include a conceptual description that gives a framework for the material in 
the chapter or part, as in the overview to Chapter 6. 
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Cross-references and hotspots 


Cross-references are pointers to related information in other sections of the 
same component or in another component. For example, you may refer a 
user from one section of a book to another section of the same book: 


See Chapter 18 for more information on date and time values. 
Section 9.4 explains how to specify an edit string for a date field. 


You may also refer a user to another book or to the online help. See The 
Digital Style Guide for more guidelines on cross-references within text. 
Also see Section 9.4.3 and Section 10.3.3.3 for information on glossary and 
index cross-references. 


In online information, users click on hotspots to display cross-referenced 
material. For example, users can easily move from one section of a book to 
another by clicking on a hotspot within text. With the DECwindows Motif 
Help System, users can also use hotspots to navigate the online help for an 
application. See Section 11.1.2.2 and Section 11.3 for more information on 
online cross-references. 


Information road maps 


An information road map (also known as a documentation map) is a 
quick guide, usually a graphic, that shows users the paths they may take to 
learn about the product and use the information component or set. A map 
can be used to describe the portions of a single course or book. Maps often 
show users the reading paths through an information set or set of courses, 
suggesting which pieces of information to use in which order, depending 
on the user’s particular area of interest. For example, the diagram shown 
in Figure 5-3 is an information road map that suggests different paths 
through the information set for database administrators and programmers. 
You can also use maps to show the menu structure of online help or even 
the menu structure of an application. 


Information road maps can be used in many different ways. For example, 
if a map describes a reading path through a particular component, you 
may repeat the map at the beginning of each part or chapter, highlighting 
the user’s current position in the map. If the book is being produced in 
hardcopy form, you might place the map on tabbed dividers or part pages 
beginning each part. You might use a poster to present the map of an 
application’s menu structure. In an online book, you can use a map in 
conjunction with hotspots to direct a user through the topics. For example, 
see the procedure maps in the online book Managing a Bookreader Library, 
available on both the ULTRIX and OpenVMS online documentation discs. 
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e Running heads and feet 


A running head is a string of text at the top of a page, while a running 
foot is a string of text at the bottom of a page. Both of these elements help 
users understand their place in a book. 


In Digital books, running feet most often identify the chapter title, 

while running heads indicate the section contents. Running heads are 
particularly effective for reference sections, where the running head 
indicates the name of the command, statement, and so on being described. 
Some groups use double-running heads, in which the top line indicates the 
family of items being described and the bottom line indicates the particular 
item being described. For example, a chapter on functions might have the 
following double-running head: 


Statistical Functions 
AVG 


Statistical Functions identifies the general section content, and AVG 
identifies the particular function discussed on that page. 


Place running heads and feet on the outside edges of pages, so that they 
are on the left edge of left-hand (verso) pages and on the right edge of 
right-hand (recto) pages. 


e Icons and margin notes 


An icon is a simplified pictorial representation of an idea, a situation, 

or an object. You can use icons in different ways to orient users to the 
material being discussed. For example, you may display the icons used in 
the user interface in the margin, which points the user to the discussion 
of the icon or process. You may use a margin icon to distinguish platform- 
specific information from multiplatform information. This book uses 
icons to identify the parts and chapters that discuss the user information 
environment, process, and techniques. Icons further identify the chapters 
that describe the different stages of the user information process. 


Margin notes are textual markers that can be used in the same ways as 
Margin icons. 


12.2 Design Cues 


Design cues are visual aids that reinforce structural cues or differentiate 
elements within text. For example, design cues often distinguish examples 
from text or point to the definition of a term in text. 
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Design elements include: 


¢ Typefaces and type sizes 


Using different typefaces is a simple but effective way to distinguish 
different types of elements within text. For example, Digital information 
frequently uses a serif typeface for text, a sans serif typeface for titles, and 
a monospace typeface for examples. 


You can also use different type sizes to indicate structural relationships. 
For example, while chapter titles, level-1 heads, and level-2 heads may 
all use the same sans serif typeface, you may use progressively smaller 
type sizes for these elements to indicate their relative position in the 
organizational hierarchy. 


e Emphasis 
There are a variety of typographic ways to emphasize words and phrases 
and thus differentiate different text elements. Common uses include: 


— Boldface type for new terms or the main page references in an index 
entry 


— Italic type for highlighting or for complete titles 


— SMALL CAPITAL LETTERS for subheadings or captions 


You may also use multiple colors or shading to emphasize and differentiate 
elements. 


Your choice of methods may be limited by your authoring tools and group 
conventions as well as by standards. See The Digital Style Guide for more 
information on emphasis and on color. 


Use design cues sparingly in technical information. The temptation is strong, 
particularly with desktop publishing tools, to use many different design cues 
because they are available. This proliferation of typefaces, type sizes, and 
color is often called circus poster typography because the text pages take on 
the appearance of a gaudy advertisement. However, a circus poster is designed 
to catch the user’s eye and to excite the user; it is not meant for reading at 
length. 


Also be careful not to attach too many meanings to one design cue. For 
example, using boldface type to signal both new terms that are defined in text 
and general emphasis may confuse users because they will not know when to 
expect a definition. 


When making decisions about which types of design cues to use, make sure to 
have a graphic designer as part of the team so that the cues can be designed 
as part of the total look of the information. 
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13 


Overview of Usability Studies 


The goal of user information is to help users use the product. 
Information that meets that goal can significantly reduce the 
costs of training and support. 


How do you determine if your information is successful? Most 
user information undergoes informal and formal review by 

a variety of technical, editorial, and informational reviewers. 
Chapter 6 describes the review process and what different 
reviewers look for during reviews. 


However, bringing users into the information development process early and 
often is an important way to ensure that the information suits their needs. 
You can implement usability methods at different points throughout the 
information development process. For example, during the research stage, you 
may use interviews to gather information about the users and tasks. During 
the draft stages, you may use other methods to check specific tasks or portions 
of the user information. Later in the process, you might use logging techniques 
to identify patterns in system use. Testing throughout the information 
development process helps to ensure that the information meets its goals and 
saves you, the company, and the customer time and money. 


You do not have to rely on the services of a professional usability engineering 
group to devise and implement usability studies. This chapter discusses 
techniques that you can use on your own to ensure that your user information 
meets its goals. 


This chapter discusses: 

e Planning for usability studies (Section 13.1 and Section 13.2) 
¢ Working with participants (Section 13.3) 

¢ General process for conducting usability studies (Section 13.4) 
e¢ The types of usability methods, including: 


— Questionnaires (Section 13.5) 
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— Telephone interviews (Section 13.6) 
— Usability edits (Section 13.7) 

— Summary tests (Section 13.8) 

— Read and locate tests (Section 13.9) 
— Contextual inquiry (Section 13.10) 


Section 13.12 summarizes the different types of usability studies and their 
benefits. 


13.1 Deciding What to Test 


You may not have the time or resources to test an entire information set or 
even an entire component. Therefore, you must identify the most important 
material and focus your efforts on those critical parts. Critical pieces might 
include: 


¢ Procedural material 

¢ Material used most frequently 

¢ Material that might be confusing for users 

¢ Information critical to the primary use of the product 

¢ Safety procedures | 

To identify the critical pieces, answer the following questions: 


¢ Which user tasks are most important for the target audience? For 
example, critical user tasks may include installing the product or using 
certain features. 


¢ What are the product goals? For example, the goals may include the 
customers’ ability to install the product in 20 minutes. 


e¢ What are known problems with the product and information set? Check 
the project archives for reader comment cards and product problem 
reports. There may also be electronic bulletin board discussions (such as 
VAX Notes™ conferences) that discuss the product’s success and problems. 
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13.2 Writing a Testing Plan 


Ideally, you include your usability testing plans in the information plan. 
However, you may not know enough when you write the information plan to 
plan all usability evaluations, particularly for a Version 1.0 product. Whether 
or not you include the testing plans in the information plan, you can still 
devise usability studies throughout the draft and review process. 


To plan for usability evaluations, you need to understand the following 
elements: 
e Testing constraints 
State the limitations that affect the testing, such as restrictions on time or 
expenses, the availability of suitable participants, or the availability of the 
product or a prototype. 
¢ Testing method 
Specifies the usability method you plan to use and the rationale for using 
that type of test. 
e Testing goal 
Includes each of the following components: 


— The performance objective states what you want users to be able to 
accomplish with the information being tested. 


— The condition specifies what resources or knowledge the participants 
must have. 


— The measurement criteria specify how you will determine if the 
information meets its usability goals. When you set the measurement 
criteria, consider how critical the task is for using the product. Set the 
measurement criteria very high for critical tasks. 


For example, Figure 13—1 shows the testing plan for an installation component. 
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Figure 13-1 Sample Usability Testing Plan 


Constraints: 

We need five participants who have never installed DECproduct. In addition, we 
must have at least 2 weeks between the first draft and the second draft dates to 
run the sessions, evaluate the responses, and incorporate the results into the 
second draft. In addition, we must have a commitment from engineering to change 
the installation process if necessary. 


Testing method: 

Formal usability edit. Observers will watch the participants install DECproduct, 
asking them to talk aloud during the session so that the observers can determine 
when the participants hesitate or have problems in following the instructions in the 
installation guide. A 1—hour (maximum) installation process for DECproduct is 
vital to its place in the market. Watching and listening to users inexperienced with 
such an installation is the best way to determine problems in the description of the 
installation procedure. 


Testing goal: 
Performance objective: \nstall DECproduct. 


Conditions: Participants have access to a prototype of DECproduct, a copy of the 
DECproduct Installation Guide, and all other user information associated with the 
product (for example, letters, release notes, parts lists, and other user information). 


Measurement criteria: 95% of the participants successfully install DECproduct within 
1 hour (when users invoke the product, it runs as expected). 


13.3 Working with Participants 


Knowing how to work with participants is vital to the success of any usability 
study. You may use customers and employees as participants. The procedures 
for contacting customers are more formal than the procedures for contacting 
internal employees. 
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13.3.1 


13.3.2 


13.3.3 


Recruiting Customers as Participants 


To find customers interested in participating in your study, work with 
product management, the field test administrator, the product’s marketing 
representative, and sales account representatives. Customers who submit 
product problem reports may be interested in helping you improve the user 
information. In addition, you may also have contacts through a user group or 
special interest group. 


After you identify potential participants and before you make any contact with 
customers, make sure you call the appropriate sales account manager. Account 
managers must be informed of any contact between you and their customers 
so that they can be fully informed when talking with customers. You may also 
want to talk with the local service representative before contacting customers. 


When working with customers (or anyone outside your company) on projects 
that involve prototypes or unannounced products, you must be sure that the 
participants sign a nondisclosure agreement. A nondisclosure agreement 
is a legal document that ensures customers will not communicate information 
about the products to other people outside your company. 


Recruiting Internal Employees as Participants 


There are a variety of ways to find internal employees who might be interested 
in acting as participants: 


e Ask the members of the project team or other colleagues if they know of 
potential participants. 


e Send memos or mail messages to internal mailing lists to reach different 
groups of employees, or use your product interest list. 


e Post electronic notices in relevant bulletin board discussions (such as 
VAX Notes conferences). 


e Post hardcopy notices on bulletin boards at sites with qualified 
participants. 


Requesting Participation 


When you call customers or internal employees to ask them to participate in ~ 
the study, always estimate the amount of time required for the session. People 
are more likely to volunteer if they know how much time they are being asked 
to commit. Briefly describe the product, the procedure, and any prerequisite 
knowledge or skills. Make it clear that you are studying the user information, 
not the participant. Example 13—1 shows a sample request for participation. 
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Example 13-1 Requesting Participation in a Usability Study 


Usability Study 
Call for Participants 


Hello, 


We will be conducting a usability study on a Digital product that 
requires users to be familiar with personal computers and the MS-DOS® 
system. The purpose of this study is to help make this product easier 
for our customers to use. 


For this study, we need volunteer participants who have experience in 
some or all of the following procedures: 


o Using DOS commands to do tasks such as: 


Creating and editing batch files 

Using directories 

Setting path names 

Copying and backing up files and disks 
Initializing disks 


Oo Installing PC software (MS-DOS system and applications) 


o Installing PC communications hardware, such as Ethernet 
cables in a local area network or communications options 
in a PC system 


© Installing personal computer (PC) hardware 
Participants must NOT have experience in: 

o Managing an OpenVMS system 

o Installing or managing a Digital PCLAN/Server system 


This study will require each participant to spend up to one full day, 
or, more likely, one half day, depending on which tasks are to be 
performed. We would like to conduct the studies sometime between 
December 2 and December 16, 1991. 


It is possible that we will not be able to include everyone who has 
volunteered for this study. We need some information about any 
experience you might have had with personal computers and the 
OpenVMS operating system. Attached is a brief questionnaire. 

Please take a few minutes to answer the questions, and return 

your answers to me as soon as possible. 


You can either send your answers in an electronic mail message to 
NODE::USER, send written answers to me at [mailstop], or call me 
at 555-1212. 


(continued on next page) 
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13.3.4 


Example 13-1 (Cont.) Requesting Participation in a Usability Study 


Thank you for your interest in the upcoming usability study for 
DECproduct. Your participation in these studies will be a valuable 
contribution to help make Digital products easier for our 
customers to use. 


Thank you, 
[Name ] 
[Group name] 


Screening Participants 


After you contact the people who have expressed interest in participating in 
the study, screen the candidates. Select only those participants who match 
the description of your audience. If you have more than one audience that you 
want to study, include participants who represent the full range of people likely 
to use the product. 


Use a questionnaire or an interview to screen candidates. Ask all candidates 
the same questions. Be careful to ask unbiased questions, and do not 

emphasize which characteristics you want and which you do not want. Select 
the participants based on how well they fit your target audience or audiences. 


Example 13-2 shows a questionnaire for screening participants for a usability 
study of an installation procedure. 


After you choose the participants, thank the candidates whom you did not 
choose. Explain that, based on their responses to the questionnaire, they do 
not fit the target audience. If candidates were particularly interested but did 
not fit your needs, you might keep them on your interest list for future studies. 


Example 13-2 Screening Candidates for a Usability Study 


1. Have you ever installed personal computer (PC) hardware? 
No 


___ Yes - Briefly describe the PC hardware you have installed. 


2. Have you ever installed communications hardware, such as 
Ethernet cables for a local area network or communications 
options in a PC system? 


(continued on next page) 
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Example 13-2 (Cont.) Screening Candidates for a Usability Study 
No 


___ Yes - Briefly describe the communications hardware you 
have installed. 


3. Have you ever installed PC software (operating systems or 
applications)? 
No 


___ Yes - Briefly describe the PC software you have installed. 


4, Are you familiar with DOS commands? 
No 


Yes - Which of the following have you done? 


Create and edit batch files 
Use directories 
Set path names 
Copy and back up files and disks 
Initialize disks 
Any others? If so, please list below: 


5. Are you familiar with OpenVMS system management tasks? 


Yes - Which of the following have you done? 


Install or update the OpenVMS operating system 
Install or update any OpenVMS layered product 
Create OpenVMS user accounts 

Back up OpenVMS files and disks 

Manage print and batch queues 

Start up or shut down an OpenVMS system 

Any others? If so, please list below: 


6. Depending on which tasks you will be doing in this 
study, it will require either one half day or a full day 
of your time. The studies will be conducted during the 
weeks of December 2 and December 9. Please list the 
three days during these two weeks that would be 
convenient for you: 


(continued on next page) 
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Example 13-2 (Cont.) Screening Candidates for a Usability Study 


7. Studies requiring volunteers with PC experience will also be 
conducted sometime in Q3 (January, February, or March). If, 
for some reason, you are unable to participate in the December 
studies, would you be interested in participating in future 
usability studies? 


No 


Yes 


Please include your name, electronic mail address, and DIN. 
Thank you! 


13.3.5 Scheduling Usability Studies 


After screening the candidates and choosing the most suitable participants, 
contact each person and schedule a time for the study session. Tell each 
participant that you will send mail or call a few days in advance to ensure that 
no scheduling conflicts have developed. 


13.3.6 Reminders and Follow-Up 


A few days before the usability session, call or send electronic mail to remind 
participants of the date and time of their sessions. If a scheduling conflict has 
developed, try to reschedule the session. 


After the session is complete, be sure to follow up with each participant by 
letter or phone: 


e Thank them for their participation. 


¢ Let them know how they can learn about the findings if they are interested. 


13.4 General Process for Conducting Usability Studies 


No matter which testing method you use, developing a usability study follows 
the same general process: 


1. Design the study. It is helpful to have someone familiar with the particular 
method review the material at this stage. 


2. Ask several people representative of the users to perform the test. This 
pretest (or pilot) helps to identify and solve unanticipated problems in the 
wording or the amount of time needed to complete the session. In addition, 
participants may respond in ways you had not anticipated. The pretest 
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also shows when the material is more complex than anticipated and needs 
to be simplified. 


3. Revise the study based on the results of the pretest. As needed, edit the 
material for content, layout, sequencing, and style. Make sure the material 
is worded clearly. Eliminate bias and jargon. 


Conduct the study. 

Analyze and interpret the data. 

Report findings in oral and written reports. 

Incorporate changes to the information based on the findings. 


Retest. 


Oot GY ON 


13.5 Questionnaires 


A questionnaire is a set of questions that you can mail to participants or ask 
in telephone or face-to-face interviews. Questionnaires are particularly useful 
for collecting the following kinds of information: 


e Facts. For example: 

How long have you worked with DECproduct? 

How often do you use the DECproduct reference manual? 
¢ Attitudes. For example: 


How usable is the information in the DECproduct Installation 
Guide? Circle the number that best represents your answer: 


Not at all Extremely 
usable usable 
1 2 3 4 5 


¢ Beliefs. For example: 


What aspects of the DECproduct Installation Guide make it 
easy to use? 


Although questionnaires may seem easy to develop and administer, you must 
plan for them and test them. Otherwise, they may result in low response rates, 
poor interviews, and uninterpretable data. 
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Use the following process to ensure that your questionnaire is well designed: 


1. 


Decide what information you want to collect and how you plan to analyze 
the data. 


Decide how you will deliver the questionnaire: 


Hardcopy through mail 
Electronic mail 
Telephone interview 


Face-to-face interview 


Your delivery method affects the design of the interview. For example, if 
you decide to use electronic mail, you might design the questions to fit on 
a 25-line screen. If you decide to use telephone interviewing, design the 
questionnaire to aid the interviewer. 


Write a first draft of the questionnaire. Consider the type of questions you 
want to ask participants: 


In an open-ended question, answers are not predefined. Participants 
fill in their own answers. For example: 


What suggestions do you have for improving the DECproduct 
Installation Guide? 


In a close-ended question, answers are provided. The user makes a 
choice among answers. For example: 


What is your general opinion of the information for the DECproduct 
applications? (Circle only one number.) 


Poor Fair Excellent 
1 2 3 4 5 


Which of the following documents did you find most useful 
in learning the DECproduct software? (Circle only one letter.) 


a. User's Guide 
b. Reference Manual 


¢c. Quick Lookup Guide 
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e You may also combine open-ended and close-ended questions. For 
example: 


Do you use any collections of symbols to prepare your scientific 
reports? 


No 


Yes What types of symbols are important to you? 
(Please list the types of symbols.) 


I use the DECproduct Reference Manual mainly for: (mark only one) 
___ Quick reference for syntax 
___ Advanced reference information that isn’t on line 
____ Examples for coding 


____ Other. Please explain: 


4, Use the following guidelines when writing the questions: 


e Place the most important question first and demographic questions 
(about age, occupation, address) last. Make the first question in 
particular easy to understand, applicable to all participants, and 
related clearly to the main purpose of the study. 


e Ask one question at a time. Make each question specific, technically 
accurate, and related to a specific goal. Group together questions that 
are similar in content or structure. 


° Make your answer categories as inclusive as possible. For example, if 
you ask a question with a range of possible answers, give the complete 
range, as follows: 


How long have you been using DECproduct? (Check one iten.) 
___ Never 

Less than 1 month 

1-3 months 

3-6 months 


More than 6 months 
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¢ Questions should require minimal effort from the participants. For 
example, have participants circle answers rather than write them in. 
In an online questionnaire, minimize the amount of tabbing or spacing 
needed to answer a question. 


e Use transitions to start a new group of questions, to start a new page, 
or to break up a long series of questions on the same topic. 


¢ If possible, make sure that each question fits on a single page or video 
screen and that the questions and answers are arranged vertically. For 


example: 
Use 
Question 
___ Response 1 
Response 2 
Response 3 
Response 4 
Do not use 
Question 
___ Response 1 ____ Response 2 
___ Response 3 ____ Response 4 


¢ Make sure that participants can clearly distinguish questions from 
answers. 


e Give instructions about how to answer questions and when and where 
to return the questionnaire. 


5. Attach a cover letter to the questionnaire. 


Specify when and where to return the questionnaire. Decide how to follow 
up with people who do not respond to the first questionnaire. 


Section A.4 contains a quality checklist for questionnaires. 


13.6 Structured Telephone Interviews 


A structured interview is a conversation with one or more participants based 
on a prepared set of questions or a script. There are two types of structured 
interviews: 


e¢ Telephone interviews 


e Face-to-face interviews 
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This section concentrates on telephone interviews, but the processes are 
similar. 


You can use a telephone interview to: 

e Gather facts and opinions about the user information and the product 

e Ask more complex questions than you can in written questionnaires 

e Explore the participants’ answers more fully than in written questionnaires 

° Follow up with people who have participated in other forms of testing or 
inquiry 

Section A.5 contains a quality checklist for telephone interviews. 


Note 


While you can call users without any advance planning, this is not 

the recommended method for conducting telephone interviews. Such 
unplanned interviews interrupt the participants’ work. In addition, the 
participants cannot prepare for the interview, and the information you 
receive may be less detailed. 


When setting up interviews, you may or may not provide the 
participants with copies of the questions to be asked. However, 

the more material the participants have before the interview, the more 
information they will be able to give during the interview. 


Use the following guidelines in designing and implementing a telephone 
interview: 


¢ Design the questionnaire for the type of interview. 


If the participants will not have a copy of the questionnaire, you need to 
add introductory and explanatory material, a script for the interviewer to 
follow in explaining the study to the participant. If both the interviewer 
and the participants will have copies of the questions, you may have two 
versions: the participants have a copy with only the questions, while the 
interviewer's copy includes some explanatory text and coding information. 


If the participants have not agreed in advance to the telephone interview, 
the interviewer must give the participant the opportunity to decline to be 
interviewed. 
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When you design the telephone interview, you must consider two separate 
audiences: 


Participants Interviewers 
Might not expect telephone calls. Must keep constant the pace of the 
dialogue. 


May let their attention wander from Must listen for changes in the mood or 
the conversation to other work they attention of the participants. 

have at hand or may be interrupted 

by coworkers. 


Can tire more quickly than in a Must be able to both read questions and 

face-to-face interview. write down the answers while holding the 
telephone. 

May lack the visual cues to follow Must be able to give information about the 

the questions (if they do not have product. 


a copy of the questionnaire). They 
may therefore have trouble following 
the questions or be unsure when the 
interviewer expects a response. 


Contact participants to introduce the upcoming interview and establish 
your credibility. Include the following information: 


— Who you are 

— The name of your company and group 

— The date and time you will call 

— How the person was selected for the interview 

— The goal of the interview 

— The anticipated length of the interview (derived from the pretest) 
— The benefits of the study 


— The name and telephone number of the project leader (so that the 
participant can check to make sure this is a legitimate study) 


Train all interviewers in proper telephone interview techniques. 


Design the training to cover pacing, etiquette, how to handle questions 
from participants, how to respond to emotional participants, how to write 
answers as the participant talks, and how to probe for more detailed 
responses. 
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Prepare a list of answers to the following questions that users often ask 
during interviews: 


— What is the purpose of the interview? 

— How doI know who you are? 

— Is the information anonymous? Is it confidential? 
— Dol get a copy of the results? 

— Whois my sales representative? 


— How can I order this user information? (Or hardware, software, and so 
on) 


13.7 Formal and Informal Usability Edits 


A usability edit is a testing method in which participants make specific notes 
when they have problems (or success) using the information with the product 
to perform tasks. 


Usability edits can identify frequently used sections of the information as well 
as helpful or particularly usable sections. The user feedback is an indication of 
where the product and the user information need improvement. Usability edits 
can point out the following types of problems: 


Ambiguous or misleading information 

Extraneous information 

Gaps in explanations or procedures 

Problems with the navigational cues, such as missing index entries 
Undefined or unclear terminology 


Missing examples and graphics 


There are two types of usability edits: 


Formal 


In a formal usability edit, observers watch each participant and record 
any disruptions in the user’s task flow. (The observers may be members 
of the information team or include other project team members.) A formal 
usability edit may last from 1 to 4 hours. See Section 13.7.1 for more 
information on formal usability edits. 
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¢ Informal 
In an informal usability edit, you give participants the user information, 
access to the product, and a coding scheme for marking the information 
as they use the product. An informal study may occur over weeks, even 
months. See Section 13.7.2 for more information on informal usability 
edits. 


The type of usability edit you choose depends on the time that you and the 
participants can spend together, the number of usability issues you think 
they will find with the information, and the type and amount of information 
you need. If you think there may be many usability issues, conduct a formal 
usability edit. 


Because usability edits are easy to administer, you can repeat them throughout 
the information development process. Indeed, they are most helpful when you 
conduct several studies on the different revisions of the material. 


13.7.1 Formal Usability Edits 
Use the following process when conducting a formal usability edit: 
1. Give the participants the user information and access to the product. 


2. Give the participants a written series of tasks that they will perform while 
you observe them. 


Ask the participants to talk aloud while they try to accomplish the tasks. 


4. Observe the participants, noting hesitations, errors, and so on, which are 
indications of usability problems. 


5. At the end of the session, discuss what occurred during the session. 
Ask the participant to discuss areas that were particularly frustrating 
or difficult. You may also ask the participant questions based on your 
observations. 


13.7.2 Informal Usability Edits 


Use the following process when conducting an informal usability edit: 


1. Give the participants a copy of the user information and make sure they 
have access to the product. 


2. Explain the coding scheme you want the participants to use in marking 
the information. Figure 13-2 shows a sample coding scheme. The coding 
scheme lets them know what types of information you are looking for. 
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Figure 13-2 Coding Scheme for an Informal Usability Edit 


® Draw a line in the margin next to any text you read. 


2 © Squiggle in the margin next to any text you skim. 


® Write in missing steps or index entries. 


e CircleGundefined>terms. 


® Underline ambiguous or confusing sections. 
>K © Put a star in places where examples or figures would help. 
© Cross out extraneous infOresafion or redundant information. 


1 © Place an exclamation point next to helpful material. 


3. Make arrangements for collecting the comments from the participants on a 
specific date. 


4. When you collect the comments, briefly discuss the comments with each 
participant. Make arrangements for how you will contact the participant if 
you have questions. 


13.8 Summary Tests 


A summary test is a testing method in which participants read a segment 
of user information and then summarize the major points. The difference 
between the participants’ responses and a summary provided by the person 
who wrote the user information determines the usability of the material. 


Summary tests are particularly useful in determining if participants 
understand conceptual information or a sequence of tasks. You can also 
use the tests to evaluate the clarity and usefulness of figures and tables. 


Summary tests require little preparation and little time to conduct. Many 
times, you can find internal employees who represent the target audience 
closely enough to participate in summary tests. The tests may take as little 
time as 10 minutes for each participant; they may last longer, depending on 
the length of the material you are testing. Because you do not need to watch 
each participant, you can conduct summary tests with several participants at 
one time. 
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Use the following process to conduct a summary test: 


1. Ask the writer to write down the main points of the material to be tested. 
Determine how closely the participants’ answers must match the writer’s 
summary for the information to meet its usability goal. 


2. Ask the participants to read the information being tested. Tell them that 
you will ask them to write down the main points of the material later. 


3. After a suitable amount of time, check that most participants have finished 
reading the material. 


4. Ask the participants to write down the major points of the material without 
looking at the material. 


5. Collect and evaluate the responses. 


13.9 Read and Locate Tests 


A read and locate test is a usability method in which participants try to find 
information that answers particular questions. Read and locate tests measure 

the effectiveness of navigational cues, such as the table of contents and index, 

and the clarity of the information. A component meets its usability goals if the 
participants can: 


e Find the answers to the questions 

e Find the answers in the place you expect them to look 
Read and locate tests can help you identify: 

¢ Buried information 

¢ Missing information 

e Redundant information 


Writing the Questions 
In designing the read and locate test: 


¢ Focus on key tasks that users perform with the product. 


e Test both material that you feel is strong and material that you feel is 
weak. 


e Balance the number of easy and hard questions, and mix the order of 
questions. 
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Conducting the Session 
Use the following process to conduct the session: 


1. Give the participants a set of instructions, the questions, and the material 
being tested. Figure 13-3 shows a sample instruction sheet. 


Figure 13-3 Instruction Sheet for a Read and Locate Test 


This study asks you to answer certain questions. Use the DECproduct Guide to 
Database Management and Performance to look up the answers to the questions 
even if you think you know the answer. If you cannot find an answer, simply write 
down the time and move to the next question. 

For each question, please provide the following information: 

® The time you started looking for the answer 

© The time you found the answer 

® The number of places you looked before finding the answer 

© The section number of the answer 


© The answer 


Remember, we are not tetsting your skills and knowledge —— rather, we are testing 
the document. 


Any additional comments are welcome. 


Thank you for your participation! 


2. Ask the participants to write specific answers and to include where they 
found the answers, including section or page numbers. 


3. Watch several participants. This gives you a sense of how the participants 
search for information as well as where they look for it. Observing 
also gives you a sense of how long it takes the participants to find the 
information. You also have the opportunity to ask participants questions 
about what they are doing at particular points during the session. 
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Follow up with a short interview of the participants. (This may be 
particularly helpful if you were not able to observe the session.) You 
may use an attitude questionnaire to check the participants’ confidence 
in finding the information about the topic. You may also use face-to-face 
interviews to solicit the participants’ ideas for improving the information’s 
usability. 


Analyzing the Results 
Use the following process to analyze the data from the study: 


ds 


For each question, determine how many participants found the expected 
answer. 


For each question, determine how many participants looked for the 
information in the place you expected. 


Based on the findings, decide how to change the user information: 


e If many participants answered the question correctly and found the 
information in the expected place, the user information most likely 
meets its usability goals. 


e If many participants looked in the expected place but did not find the 
expected answer, consider making the following changes: 


— Move the information so that it is more visually prominent. 
— Clarify the information. 
— Reorder the information so that it receives more emphasis. 


e¢ If many participants did not look in the expected place but found the 
expected answer, consider making the following changes: 


— Reorder the information. 


— Remove unnecessary information from the index or table of 
contents. 


— Remove redundant information. 


¢ If many participants did not look in the expected place and did not find 
the expected answer, consider making the following changes: 


— Add missing information. 
— Change the organization. 
— Clarify the terminology. 


— Move information so that it is more visually prominent. 
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— Reorder the information so that it receives more emphasis. 


In addition, you may also use another test method, such as an interview, 

to complement the read and locate test. This can help you determine if the 
test was at fault or if you need to revise the task analysis you did during the 
research and planning stages (see Chapter 3 and Chapter 4). 


13.10 Contextual Inquiry 


Contextual inquiry is an interviewing method that involves questioning 
and listening to users as they do their regular work in their normal work 
environment. 


Contextual inquiry can provide: 

¢ Descriptions of tasks and sets of tasks that users perform 

¢ Information on how different products are used together 

e The terms people use in their daily tasks 

¢ Detailed design data 

¢ Descriptions of usable and disruptive aspects of the product 


Contextual inquiry is thus a powerful tool for analyzing the audience and 
product and for determining the accuracy of your view of how the product 
and user information are used. For example, contextual inquiry may show 
that customers are confused by the terminology in the user information. The 
participants consistently use term x as they describe their work, but the user 
information uses term y. You therefore need to reconsider the terminology in 
the user information. 


If possible, record the session on audiotape or videotape so that you can 
concentrate on the participant during the interview, not on taking notes. You 
can then use the tape later for your analysis. 


It is also a good idea to have two interviewers. One person acts as the primary 
interviewer. The other person operates the camera or tape recorder or takes 
notes and highlights important aspects of the interaction people have with 
their computer systems. The notes include events that: 


¢ Create a smooth work flow 
¢ Cause repeated disruptions in work 


e Are inconsistent in the participants’ view 
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Use the following process to conduct a contextual inquiry: 


1. 


In advance, contact each participant to make the arrangements for the 
interview. 


Explain the purpose of the interview and the procedure. Tell participants 
how long you expect the interview to last; a typical session may last up to 
2 hours. 


Ask the participants if they object to being taped. If they do not, find out if 
there are any special arrangements you need to make at the participants’ 
sites. (You may have to talk with their management or security staff.) Tell 
them that you will bring a recording consent form that specifies how the 
tapes will be used. 


When you meet with each participant, introduce yourself and discuss the 
focus for the interview. 


The focus may be what people find usable and unusable about a product, 
how different products work together, or what tasks are important to 

the participants’ work. Ask participants to briefly describe what they 

will be doing during the interview and what tools they will use. Tell 
participants that you will observe their work, ask questions, and share 
your interpretations of the ways in which the computer system supports or 
impedes their work. 


Ask the participant to sign the recording consent form. 


Make it clear to participants that they can take a break at any time. 


If a participant has to answer the telephone or talk with a colleague during 
the interview, respect the person’s privacy and ask if you should leave the 
office. 


As you observe the participants, be aware of how the social and physical 
environment affects their work. Is the user information located in an open 
office? Are there distractions? 


When you see puzzled looks, pauses, rereading of the user information, or 
signs of frustration, talk with the participant about what is happening. 
Ask open-ended questions such as “What are you trying to do?” “What did 
you expect to find in the user information?” “How could the system make 
this task easier for you?” 


At the end of the interview, summarize the session and share your 
interpretation with the participants. Ask for samples of nonconfidential 
work that you can take with you as reminders of the type of work. 
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Ask questions about any events that you did not understand during the 
interview. Also ask any standard questions that you want all participants 
to answer (including demographic information). 


7. Thank the participants and ask if you may call later to clarify any issues 
that come up when you review your notes or the session tapes. 


8. Follow up with a thank-you note to each participant and to any managers 
who were involved in setting up the interviews. 


13.11 Other Usability Study Methods 
The following list briefly describes additional usability study methods: 


e Critical incident tests 


In a critical incident test, you ask participants to describe successful or 
unsuccessful events as they use a product. The participants also rate how 
critical the incident is for completing the task. This type of information 
can help the project team set priorities for revisions to the product or 
information. 


¢ Logging 
Logging is a method of collecting the participant’s use of a product or 
the user information. Logging can help you analyze tasks, eliminate 
unnecessary features or information, and determine the most common 
ways users do tasks. 


The capability to capture users’ keystrokes and system messages may 

be built into the software. If so, all users need to know that the logging 
capability exists and must have the option of turning off the logging 
feature. Logging is a tool for improving the product, not for evaluating the 
users. 


e Performance tests 


A performance test is similar to a formal usability edit except that 

the participants are timed as they work on a task and the number of 
errors they make are noted. You then revise the product or information to 
improve the time needed for the task and to reduce the number of errors. 
Performance tests are often videotaped. 


e Protocol-aided revision 


In a protocol-aided revision, participants are asked to complete a given 
task and talk aloud while they do the task or read the user information. 
These sessions are usually audiotaped or videotaped, often in a lab setting. 
The transcription of the session is called a protocol. Data from these 
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sessions can be very rich, but it takes much time to transcribe and analyze 
the data. 


Focus groups 


Also known as group interviews, focus groups are a gathering of 
several people to discuss a certain topic. After the participants fill out a 
short questionnaire about their opinions on the topic, a facilitator leads a 
group discussion to determine areas of agreement or disagreement. 


Focus groups are best for gathering wish list items, general attitudes, 
and reactions to prototypes or products. However, focus groups may be 
expensive and yield mainly qualitative data. They also require a trained 
facilitator. 


13.12 Summary: Selecting a Usability Method 


Table 13-1 describes the benefits of and issues with the testing methods 
discussed in this chapter. 


Table 13-1 Comparison of Usability Study Methods © 


Study Method Benefits | Issues 
Mail questionnaire Low cost. Low response rate possible. 
Easy to distribute to many people. High probability of biased 
Fast implementation. sample. 
Difficult to get detailed 
answers. 
Structured telephone Low cost. Questions must be relatively 
interview simple. 


High response rate. 


Lets you ask follow-up questions. Requires interviewing skills. 


Participants might be 
distracted. 


(continued on next page) 
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Table 13-1 (Cont.) Comparison of Usability Study Methods 


Study Method Benefits 


Issues 


Lets you see user interact with 
product. 


Formal usability edit 


Gives qualitative and quantitative 


Artificial task. 
Requires interviewing skills. 
Requires a working product or 


data. prototype. 
Informal usability edit Quick. Requires a working product or 
Low cost. prototype. 


Requires few resources. 


Requires little training. 


Quick. 
Low cost. 


Summary test 


Lets you isolate specific areas to 
test. 


Requires little training. 


Artificial task. 


Not useful for long sections. 


Read and locate Low cost. 
Requires little training. 


Yields data on information retrieval. 


Artificial task. 


Requires time to develop the 
questions. 


Requires another method 
to determine representative 
tasks. 


Lets you observe the whole system 
while the user works. 


Contextual inquiry 


Yields information about user tasks. 


Time-consuming to analyze 
data. 


Interrupts participant’s work. 
Yields only qualitative data. 
Requires interviewing skills. 
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(continued on next page) 


Table 13—1 (Cont.) Comparison of Usability Study Methods 


Study Method 


Critical incident 


Logging 


Performance test 


Protocol-aided revision 


Benefits 


Can choose a convenient method 
of distribution: online log, written 
diary, questionnaire, or interview. 


Requires minimal development 
time. 


Rates the importance of problems. 


Gives qualitative usage data. 
Yields a large amount of data. 


Lets you see user interacting with 
product. 


Yields quantitative data. 


Lets you analyze thought processes. 


Can be compared with published 
data. 


Issues 

Time-consuming for partici- 
pant. 

Interrupts participant’s work. 


Requires special software to 
collect data. 


Time-consuming to analyze 
data. 


Artificial task. 


Requires a working product or 
prototype. 


Time-consuming to analyze 
data. 


Requires scheduling. 
Requires interviewing skills. 


Time-consuming to analyze 
data. 


Often requires follow-up. 


(continued on next page) 


Overview of Usability Studies 241 


Table 13—1 (Cont.) Comparison of Usability Study Methods 


Study Method Benefits issues 
Focus group Yields information about general Requires a trained facilitator. 
SBCs: Expensive. 


Provides group’s understanding of 
problems and solutions. 


More flexible than mail question- 
naires. 


Lets you explore the participants’ 
answers. 
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714 


Conducting Trademark Searches 


During the draft and review process, the writer and editor 
must keep track of which trademarks are used and how 
they are used. The editor may use the project style sheet 
(see Section 9.3.1) to maintain a list of trademarks. The 
information team needs to know the following information: 


e Ifa product or service name is a trademark or service mark =e 
¢ Whether the trademark is registered or not 

¢ The owner of the trademark 

e¢ The correct form of the trademark 


This chapter discusses how to track elusive trademarks. See The Digital Style 
Guide for details on how to use and refer to trademarks. 


Trademark information, like any technical information, may change frequently. 
If you do not have an updated list of trademarks, ask your product manager or 
legal representative to get the correct information. Specify exactly what you 
need to know, and give a deadline by which you need the information. In most 
cases, using either the product manager or legal representative as a resource is 
the correct procedure, letting the writer and editor concentrate on developing 
the user information rather than researching trademarks. 


However, there may be times when neither resource is available. Use the 
following resources to research trademark information: 


¢ Your company library may research trademark information. Call the 
library and ask for the Reference Desk. To help the librarian research the 
trademark, provide the following information: 


— Product name 
— Name of the company that owns the trademark, if you know it 


— How you are using the trademark (for example, referring to it in a user 
manual) 
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— When you need the information 
— Any other useful information, such as the type of product or service 


e Third-party marketing literature and product documentation usually 
contains information about company trademarks. 


e If you know the name of the company that owns the trademark and can 
get the telephone number, direct contact may be the fastest way to check 
the information. Call the company and ask for their legal department. If 
the company does not have a legal department, ask for the publications, 
marketing, or sales department. 


Give your name, title, and the name of the company you represent. Be 
specific about the information you need and the deadline by which you 
need the information. 
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PartlV 


Appendixes 


This part contains two appendixes: 


e Appendix A contains a series of checklists for assuring the quality of 
product and audience research, information plans, online information, 
usability tests, and reproduction packages. 


e Appendix B is a selected bibliography of information on technical 
communication. 


A 


Quality Assurance Checklists 


Use the following checklists as guidelines for quality assurance during the 
information development process. The checklists cover the following topics: 


Audience and product research (Section A.1) 


Information plans (Section A.2) 


Online information (Section A.3) 


Questionnaires for usability studies (Section A.4) . 


Telephone interviews for usability studies (Section A.5) 


Reproduction packages (Section A.6): 


Reproduction proofs (Section A.6.1) 
Mechanicals (Section A.6.2) 

Color and screen markup copy (Section A.6.3) 
Print specifications (Section A.6.4) 

Assembly sheet (Section A.6.5) 

Film master proofs (Section A.6.6) 
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A.1 Researching Checklist 


Use the following checklists when gathering information about your product 
and audience: 


Audience Research 
In gathering audience information, ask the following questions: 


[_] For whom is the information intended? Customers? Third-party partners? 
Internal users? 


[_] How varied are the users’ skills? 


What is their educational level? 
What is their technical background? 
What is their reading level? 


Do they have any special requirements? 


[_] What is the user environment? 


Where will the product be used? For example, will the product be used 
in a large office setting, small business, or academic setting? 


What are the standard job titles within the environment? This 
information helps to identify the groups of users and their skills. 
(However, job titles do vary across companies and cultures, so you must 
use this information carefully.) 


What is the frequency of turnover? This data can help you determine 
how much time users have to learn to use a product. 


[-] What are the work flow patterns? 


What are the major work tasks? How much time is spent on tasks? 
Who is responsible for correcting errors? Maintenance? 


What are the patterns of interaction? How many users have access to 
the information? How is data passed among users? 


How do users find the information needed for new tasks? 
Where do users go for information to solve problems? 


If there is existing user information, what pieces do users find most 
useful? Are there pieces that they do not use? 


How much time can users devote to initial training? 
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What is the effect of the product on the users? 


° Why are they interested in using the product? What parts of the 
product are they interested in? 


© Does it allow more time for other important tasks? Does it establish 
new types of jobs? 


© Does it create tasks that are repetitious or boring? Does it force users 
to work in isolation from each other? Does it force them to work 
together in unproductive ways? 


Product Research 


As you research the product throughout the development cycle, ask these 
questions: 
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What portions of the product are visible to the users? 


Is the product new? Is it an upgrade? What similar products exist at your 

company or elsewhere? What was the history of the related product in your 
company? Is there anything significant to be learned from the information 

team of that product? 


What information about the product already exists? 
What software or hardware is required for using the product? 
What types of problems is the new or upgraded product intended to solve? 


Are the product functions or tasks similar to those commonly performed 
outside the computer environment? For example, electronic mail and text 
editors are products whose tasks are familiar to anyone who sends letters 
or writes at a keyboard. The conceptual framework for such a product does 
not need extensive explanation. 


How many tasks can be performed using the product? How detailed is each 
task? Do many tasks require subtasks? 


How will the information set be distributed? (For example, will the 
information be distributed with the product kit, on a CD-ROM, in hard 
copy?) 


With what standards must the product comply? 


Will the product be translated? Will it be localized for particular 
geographies? (While this may not make a difference in the content or 
presentation of the material, it may make a difference in the process.) 


For each function and feature, ask the following questions: 


LI 


What is it supposed to do? 
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What is the result of using the feature? 

What are the defaults? 

What advantages are there in the feature? 

Are there formatting or syntax rules to watch out for? 
Does this feature enhance or replace an old one? 


Will this feature be mentioned in more than one context? 
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Do other publications need to be updated because of this information? 
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A.2 Information Plan Checklist 


Use the following checklist when reviewing information plans. The checklist 
assumes that the plan contains printing and packaging information. 


General Completeness 
The information plan: 
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Clearly describes the product and the audience. 
Clearly describes the components of the information set. 


Indicates any internationalization plans, including which components 
will be adapted or translated, scheduling needs, tools requirements, and 
file maintenance information. The plan should also name the translation 
coordinator and the internationalization group contact. 


Describes the plans for putting information on line, including the form of 
the online information (online book, reference pages, and so on). 


Includes the members of the information team and the list of reviewers. 


Gives topic outlines in sufficient detail so that reviewers can judge the 
effectiveness of the organization. 


Identifies tools to be used for creating and managing all components. 


Milestones 

The information plan lists the scheduling information for each component. The 
milestones list is complete, and adequate time is allotted for each milestone. 
Check for the following: 
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The information plan contains all major milestones, including formal 
technical and editorial reviews, online reviews, field test reviews, and 
production dates. If the internationalization plans require special reviews, 
they are included in the milestones list. 


The schedule uses actual dates, not TBS or When available. This is 
particularly important for the final information plan. 


The schedule allows enough time for all reviews. 
The schedule allows adequate time for final production. 


The plan specifies the production schedule for any online materials, 
particularly online books. 
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Production and Packaging Requirements 


Check that the information plan contains the following production and 
packaging information for each component and that the specifications conform 
to the requirements in any company publishing or manufacturing standards: 


[_] Distribution source 

[_] Name of manufacturing group contact 

[_] All component identification numbers, including the order number or part 
number 

[_] All project identification numbers, as required by group practice, such as: 

e¢ Discrete project number 


¢ Manufacturing group control numbers 


LJ 


Delivery media: hardcopy, online, or both? On what type device: 
CD-ROM? Part of product kit? 


Method of submission 


[] 


¢ Hardcopy repro 

¢ Electronic 

¢ Demand print 

Format (doctype, style) 

Trim size 

Estimated page count 

Estimated art count (including whether art is existing, revised, or new) 
Use of multiple ink colors 


Special requirements, such as four-color process art, special screens, or 
complex tables or examples 


Binding method 

Type of cover (flush, tabbed, wraparound) 
Internal dividers, if any (tabbed, nontabbed) 
Spine copy, if any 


Waiver requirements 
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Kitting information 


252 Quality Assurance Checklists 


A.3 Online Book Checklist 


Use the online information checklist to review books built for the Bookreader 
application. 


General 
Verify that the following general points are true: 
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The document is visually attractive, does not make excessive use of 
alternate fonts, and uses lists, figures, tables, and examples to organize 
information clearly. 


The conventions table contains conventions specific to the online book when 
these conventions differ from the hardcopy conventions. 


The preface contains a chapter-by-chapter overview of the book, coded with 
hotspots. 


Each chapter opening contains a list of first-level heads and their section 
references, coded as hotspots. 


The text contains references to all formal (numbered) figures, tables, and 
examples, coded as hotspots. 


Cross-references to other sections or chapters are coded as hotspots. 


Informal elements that exceed the default width of the window (such as 
unnumbered figures, tables, or code examples) are either left as is or coded 
as popups. Make the decision to code as popups based on whether the item 
will lose its usefulness if separated from its discussion in the text. 


The length of online topics is optimum. A general guideline is that topics 
should not be shorter than one quarter of a screen nor longer than five 
screens. 


[_] All heads (titles) have accompanying text. This ensures that the user sees 
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some text associated with each head when clicking on a topic. 


If possible, glossaries and listings of error messages are coded so that the 
user can access a range of terms or messages as a topic from the table of 
contents. Otherwise, the entire glossary or message appendix is one topic, 
and users must go through the topic screen by screen. 
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Checking the Table of Contents 
Review the table of contents for the following: 
[_] Click on all book elements. 


[_] Click on topic groupings (ranges) within the glossary. Read the top and 
bottom of the range to verify that all terms are present. 


Checking Elements Within the Book 
Check for the following hotspots within the book: 


Cross-references to chapters and sections. 


Chapter: Correct any place where the hotspot covers only the chapter 
number, for example, 6, instead of the whole, Chapter 6. 


Formal and informal tables: Check for overlap of column heads or column 
copy. 


Formal figures and tables: Check that the figure either fits in the window 
or can be seen by enlarging the window or scrolling. 


Informal figures: Check that informal figures do not overlap the text above 
or below. 


Popups: Check that the popup fits in the window or can be seen by 
enlarging the window or scrolling. 


Footnotes: Click on each footnote in text or tables to be sure it pops up. 


Margin icons: Check that margin icons do not overlap the text above or 
below. . 
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Skim the entire display for anything unusual (generally caused by coding 
errors). For example, double colons may appear after a Note, Caution, or 
Warning header if the format automatically adds a colon and the writer 
included a colon in the source file. 


Checking the Index 
Check the index for the following: 


[_] Move the mouse through the entries to be sure hotspots exist where 
appropriate. 


[_] Check that entries point to the correct locations in text. 
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What Not to Check 


The appearance of a Bookreader book has some variations from the hardcopy 
version. You do not need to be concerned about the following: 


e Appearance of notes, cautions, and warnings. These items may be in bold 


type on Bookreader but are not bolded in some hardcopy formats. 


Other font changes. For example, some items that are in bold type on line 
may appear in italic type in some hardcopy formats. 


Spacing problems, unless text or figures overwrite. A possible exception 
is spacing problems caused by faulty coding practices, such as extra 


paragraph markers. Be sure your coding does not introduce extra blank 
lines. 


e Appearance of fonts (for example, italic type does not translate well to the 


Bookreader). 
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A.4 Questionnaire Checklist 


The following checklist gives guidelines to consider as you create your 
questionnaire. The answer to all the following questions should be Yes. 


General 
[_] Does each question relate to a specific test goal? 
[_] Are questions technically accurate? 
[_] Can you compare your questions to existing information? 
Participants 
[_] Do you have a plan for locating potential participants? 
Do you have an adequate sample of potential participants? 


LJ 

[_] Can you justify limiting the sample of participants for security, political, 
economic, or other reasons? 

LJ 


Do you have a plan for getting questionnaires from people who do not 
respond? 


Did you give instructions for how to answer the questions? 
Do the questions fit on a page or a screen? 


iw 
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[-] Do the questions and answers flow vertically? 

[_] Can questions be clearly distinguished from answers? 
Ef 


Do you use transitions to start new lines of questions, to start a new page, 
or to break up a long series of questions on the same topic? 


Language and Focus 

Is the wording easily understood? 

Have you eliminated bias from your questions? 

Have you eliminated all jargon or obscure abbreviations? 

Have you asked one question at a time? 

Are questions specific enough? 

Have you eliminated all questions that are either too specific or too vague? 


Do the questions require minimal effort from participants? 
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Are your answer categories inclusive? 
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[_] Is the first question clearly related to the main topic? 

[ _] Is the first question easily understood and applicable to everyone? 

Order 

[_] Is the most important question first? 

[_] Are demographic questions last? 

[_] Are all similar questions grouped together? 

[_] Within a content area, are all questions of the same type grouped together? 
Implementation 

Does a cover letter accompany the questionnaire? 


Did you specify when and where to return the questionnaire on both the 
cover letter and the questionnaire itself? 


Have you planned on how to deal with follow-up questionnaires for people 
who do not respond to the first questionnaire? 


Did you pretest the questionnaire on a small sample of participants? 


tah TEI eases 


Do you have a plan for analyzing the questionnaire data? 
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A.5 Telephone Interview Checklist 
Use the following checklist to prepare for a telephone interview: 


[_] Make sure the first few questions are interesting and engaging to the 
participant. 


Make the first questions simple to answer, and include a small set of 
response categories. 


Include an open-ended question after the first few questions. 
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Make sure your script for the interview is easy to read and follow. 
Maintain a conversational tone when you talk; do not sound as if you are 
reading. For example: 


e Make sure questions, pauses for answers, and surrounding script are 
marked clearly. 


e Include transition statements and explanatory material to help 
participants understand the goal of the interview. 
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A.6 Reproduction Package Checklist 


Make sure that the hardcopy reproduction package contains the following 
items: 


Camera-ready copy, including repro proofs (repro) and mechanicals 
For reference cards, a folding dummy 


Color and screen markup copy if the component uses screens or more than 
one flat ink color 


Assembly sheet 
Final print specification 
Copy of waiver approval, if applicable 


Recto/verso page layout sheet 


The following sections contain checklists for each of these items in the 
reproduction package (except waivers). 


A.6.1 Repro Proofs Checklist 


Make sure that the repro proofs (for hardcopy repro submissions) meet the 
following criteria: 


The correct order number (or part number) is visible on the title page 
and matches the order number on the reader comment pages, print 
specification, assembly sheet, and mechanicals. 


The image position is clearly identified on the recto/verso page layout sheet 
or with trim marks or registration marks. 


Each page is complete (no missing art or text) and in order. 
All folios are uniform and in the correct position on recto/verso pages. 


There are no duplicate pages (possible exceptions are reader comment 
pages and mailers). 


There are no smears, smudges, wrinkles, extraneous toner, or excessive 
toner clustering; pasteups are clean, in the correct place, and correctly 
aligned. 


Copy is clearly legible with no broken type or filled-in letters. 


The copy is of uniform high density both on a page and throughout the 
document. 
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Copy meets your company’s specifications. For example, within Digital, 
copy must be no closer than 4.8 mm (3/16 inch) to the outside margin. 


The page count in saddle-stitched books is divisible by 4. Blank pages are 
added, if necessary. 


The repro contains the following additional pages, as applicable to your 
group: How to Order Additional Documentation, Reader Comment 
pages, Business Reply Mailer, locator pages (if tabbed dividers are used), 
slipsheets (for example, for spine inserts). 


A.6.2 Mechanicals Checklist 


Make sure that the mechanicals (for hardcopy repro submissions) meet the 
following criteria: 
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Printing instructions on the mechanical are accurate and match the print 
specification and assembly sheet. 


The type density is black and consistent. 


Trim marks, crop marks, and registration marks are clearly and correctly 
shown and back up properly. 


All elements are aligned correctly and are securely affixed. 


There is no broken type, dirt, smudges, or adhesive residue on the 
mechanical. 


The trim size is correctly marked on base art outside the trim area. 


The order number appears on every mechanical and matches the order 
number on the print specification, assembly sheet, title page, and reader 
comment pages. 


Tissue and acetate overlays are securely taped to the board outside the 
trim area and do not cover trim marks, registration marks, or instructions 
on the board. 


Tissue overlays are clearly marked for color breaks, ink bleeds, reverses, 
screens, overprints, traps, and so on. 


All printed elements (except for bleeds) appear within the trim area and do 
not intrude into the drilling or binding area. 


All words are spelled correctly and titles are correct and complete. 
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A.6.3 Color and Screen Markup Checklist 


Make sure that the color and screen markup copy (for hardcopy repro 
submissions) meets the following criteria: 
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The color and screen markup copy is part of the repro package for hardcopy 
repro submissions. The markup contains exact copies of the repro proof 
pages requiring multiple ink colors and screens. 


Color and screen markup matches the repro proofs exactly. 


Areas requiring second color or screens are precisely circled with a fine- 
point pen and do not overlap into other areas. 


Instructions for the film supplier on the title page and in the margins are 
clear, legible, and accurate. 


PMS colors and screens match the corresponding information on the print 
specification and assembly sheet. 


Pages requiring multiple colors or screens correspond one-for-one to the 
pages marked on the assembly sheet. 


The color and screen markup is reproducible on a photocopier; no color- 
coded marking system (such as highlighting pens) is used. 


A.6.4 Print Specification Checklist 


Make sure that the print specification (for both hardcopy and electronic 
submissions) meets the following criteria: 
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The hardcopy of the final print specification that goes to the film supplier 
is legible and reproducible on photocopier. This copy is included with the 
repro package. 


All fields of information are complete except for the proof approval date 
field, which is completed immediately upon approving the proof. If no proof 
is requested, this date can be entered as the reproduction package delivery 
date. 


All fields of information are accurate and conform to your company’s 
publishing or manufacturing standards. If the print specification contains 
information that is an exception to such a standard, you may need to 
include a hard copy of the approved waiver form. 


PMS ink colors are completely specified and correct. 


All specifications agree with other parts of the reproduction package. (For 
example, the ink colors given in the print specification match the ink colors 
listed on the assembly sheet and on the color and screen markup copy.) 
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No handwritten notations are included on the print specification. The 
total number of pages is accurate and matches the total page count on the 
assembly sheet and repro. 


The second-color page count matches the color markup. 


The document order number is correct and is the same as shown on the 
assembly sheet and the repro proofs, mechanicals, and page layout. 


The correct drilling and binding options have been selected. 


A.6.5 Assembly Sheet Checklist 


Make sure that the assembly sheet (for hardcopy and electronic submissions) 
meets the following criteria: 
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The order number on the assembly sheet matches order number on the 
following: 


¢ Print specification 

e Color and screen markup copy 

e Repro proofs (title page and reader comment pages) 
¢ Mechanicals (including front cover) 

¢ Recto/verso page layout sheet 


Ink colors and screen percentages marked in the special page treatment 
summary on the assembly sheet match the corresponding information that 
appears in the print specification and color and screen markup copy. 


The assembly sheet is legible and reproducible. 


All elements of the document are accounted for on the assembly sheet 
(cover, spine, chipboard, and so on). 


Pages marked for color or screens match exactly the color and screen 
markup copy. 


The page count for saddle-stitched books is divisible by 4. Blank pages are 
added at the back if necessary. 


The total page count is indicated. (It does not include front and back 
covers, internal tabbed dividers, slipsheets, chipboard, or spine inserts.) 


The assembly sheet contains a key to second-color markup designation (if 
applicable) and indicates the number of second-color pages. 


The assembly sheet contains instructions to shoot repro at 100%. 
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A.6.6 Film Master Proofs Checklist 


Make sure that film master proofs meet the following criteria: 


[_] The color and screen work indicated on the film master proofs match the 
color and screen markup copy for accuracy and position. 


The overlay and integral proofs are checked against the original 
mechanicals for color accuracy and trapping specifications. 


All pages that require film supplier changes or corrections are clearly and 
legibly marked, preferably with a red ballpoint pen. 


page numbers and corrections. 


LJ 
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[_] The film supplier’s proof approval tracking form is complete and lists all 
[|_| The package is reassembled and returned to the film supplier. 
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Publications Bookshelf 


This appendix describes resources useful to all technical communicators. The 
references are divided by subject areas: 


Standard reference works (Section B.1) 
Writing and style (Section B.2) 

Computer dictionaries and glossaries (Section B.3) 
Multiplatform information (Section B.4) 
Internationalization (Section B.5) 

Indexing (Section B.6) 

Editing (Section B.7) 

Usability (Section B.8) 

Online information (Section B.9): 

— Help (Section B.9.1) 

— Bookreader (Section B.9.2) 

Production and manufacturing (Section B.10) 
Industry standards (Section B.11) 


Engineering process (Section B.12) 


B.1 Standard Reference Works 


The Chicago Manual of Style. Chicago: The University of Chicago Press, latest 
edition. 


Hodges, John C. and Mary E. Whitten. Harbrace College Handbook. NY: 
Harcourt, Brace, Jovanovich, Inc., latest edition. 
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Roget’s Thesaurus of English Words and Phrases. Available in different forms 
from different publishers (including Doubleday, Houghton Mifflin, Longman, 
Penguin Books). 


Webster’s New Collegiate Dictionary. Springfield, MA: G. & C. Merriam, latest 
edition. 


B.2 Writing and Style 


Barzun, Jacques. Simple and Direct: A Rhetoric for Writers. NY: Harper & 
Row, 1975. 


Bell, Paula. Hightech Writing. New York: John Wiley & Sons, 1985. 


Bernstein, Theodore M. The Careful Writer: A Modern Guide to English Usage. 
New York: Atheneum, 1978. 


Brockman, R. John. Writing Better Computer User Documentation. New York: 
John Wiley & Sons, 1990. 


Brogan, John A. Clear Technical Writing. NY: McGraw-Hill Book Company, 
1973. 


Brusaw, Charles T., Gerald J. Alred, and Walter E. Oliu. Handbook of 
Technical Writing. NY: St. Martin’s Press, 1976. 


Carroll, John M. The Nurnberg Funnel: Designing Minimalist Instruction for 
Practical Computer Skills. Cambridge, MA: MIT Press, 1990. 


Copperud, Roy H. American Usage and Style: The Consensus. New York: Van 
Nostrand Reinhold, 1980. 


Corbett, Edward P.J. Classical Rhetoric for the Modern Student. Oxford 
University Press, 1971. 


Doheny-Farina, Stephen, ed. Effective Documentation — What We Have 
Learned from Research. Cambridge, MA: The MIT Press, 1987. 


Follett, Wilson. Modern American Usage: A Guide. NY: Hill & Wang, 1966. 


Fowler, H.W. A Dictionary of Modern English Usage. Oxford: Clarendon Press, 
1965. 


Gowers, Sir Ernest. The Complete Plain Words. Revised by Sidney Greenbaum 
and Janet Whitcut. Harmondsworth, England: Penguin Books, 1987. 


Haramundanis, Katherine. The Art of Technical Documentation. Bedford, MA: 
Digital Press, 1992. 


Mackh, Georgia E. and Lois Johnson Rew. “Using Access Aids to Boost 
Information Retrieval.” Technical Communication 38(2), 1991: 210-213. 
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Reference Handbook of Grammar & Usage. Derived from Porter G. Perrin, 
Writer’s Guide and Index to English. NY: William Morrow & Company, 1972. 


Rodale, Jerome Irving. The Synonym Finder. Emmaus, PA: Rodale Press, Inc., 
1978. 


Schultz, Susan I., Jennifer J. Darrow, Frank X. Kavanagh, and Marjorie J. 
Morse. The Digital Style Guide. Bedford, MA: Digital Press, 1992. 


Skillin, Marjorie E. Words into Type. Third edition. Englewood Cliffs, NJ: 
Prentice-Hall, Inc., 1974. 


Strunk, William, Jr. and E.B. White. The Elements of Style. NY: Macmillan 
Publishing Co., Inc., 1979. 


Tichy, H.J. Effective Writing for Engineers, Managers, and Scientists. NY: John 
Wiley & Sons, 1988. 


Tracey, J.R., D.E. Rugh, and WS. Starkey. STOP: Sequential Thematic 
Organization of Publications. Fullerton, CA: Hughes Aircraft Corp., Ground 
Systems Group, 1965. 


Weiss, Edmond. How to Write Usable User Documentation. Second edition. 
Phoenix, AZ: The Oryx Press, 1991. 


— . The Writing System for Scientists and Engineers. Englewood Cliffs, NJ: 
Prentice-Hall, Inc., 1982. 


Williams, Joseph M. Style: Ten Lessons in Clarity and Grace. Glenview, IL: 
_ Scott, Foresman, 1981. 


Zinsser, William. On Writing Well: An Informal Guide to Writing Nonfiction. 
NY: Harper & Row, 1980. 


For training in the Information Mapping® method of creating modular 
information, investigate the following Digital courses: 


e Strategies for Developing High-Performance Information (EY-B107E-LO) 
e Effective Reports, Proposals, and Memos (EY-8097E-L0) 
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B.3 Computer Dictionaries and Glossaries 


Edmunds, Robert A. Prentice-Hall Encyclopedia of Information Technology. 
Englewood Cliffs, NJ: Prentice-Hall, 1987. 


Freedman, Alan. The Computer Glossary: The Complete Illustrated Desk 
Reference. NY: AMACOM (American Management Association), 1991. 


IEEE Standard Dictionary of Electrical and Electronics Terms. NY: Institute of 
Electrical and Electronics Engineers, 1988. 


Webster’s New World Dictionary of Computer Terms. NY: Webster’s New World, 
1988. 


There are also a number of dictionaries and glossaries available through 
various standards bodies, including: 


ANSI X3.12-1970 (ISO Standard 2382/V, VI), Vocabulary for Information 
Processing 


ANSI/IES RP-16-1980, Nomenclature and Definitions for Illuminating 
Engineering (revision of ANSI Z7.1-1967) 


ANSI/IEEE 91-1984, Graphic Symbols for Logic Functions 


ANSI/IES 162-1963, Electronic Digital Computers, Definitions of, Terms for 
(reaffirmed 1984) 


ANSIAEEE 315-1975, Graphic Symbols for Electrical and Electronics Diagrams 
ANSI/AIEEE 610.2-1987, Glossary of Computer Applications Terminology 
ANSI/AIEEE 729-1983, Standard Glossary of Software Engineering Terminology 
ISO 7 04, Principles and Methods of Terminology 


B.4 Multiplatform Information 


You may order the following books through your regular ordering channels. 
The books are also available on the ULTRIX and OpenVMS online 
documentation CD-ROMs. 


NAS Guide to Documenting Multiplatform Products 

NAS Guide to Designing a Portable Programming Interface 
NAS Guide to Using a Portable Programming Interface 
NAS Overview 
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B.5 Internationalization 


Corporate User Publications Group. Digital Guide to Developing International 
Software. Bedford, MA: Digital Press, 1991. 


Jones, Scott, Cynthia Kennelly, Claudia Mueller, Marcia Sweezey, Bill Thomas, 
and Lydia Velez. Developing International User Information. Bedford, MA: 
Digital Press, 1992. 


B.6 Indexing 


Borko, Harold and Charles L. Bernier. Indexing Methods and Concepts. NY: 
Academic Press, 1978. 


B.7 Editing 


Boston, Bruce O., editor. Stet! Tricks of the Trade for Writers and Editors. 
Alexandria, VA: Editorial Experts, Inc., 1986. 


Dragga, Sam and Gwendolyn Gong. Editing: The Design of Rhetoric. 
Baywood’s Technical Communication Series. Jay R. Gould, editor. Amityville, 
NY: Baywood Publishing Company, 1989. 


Judd, Karen. Copyediting: A Practical Guide. Los Altos, CA: William 
Kaufmann, Inc., 1982. 


McCormick, Barbara S. How to Function as a Schizoid Editor. Washington, 
DC: Society for Technical Communication, 1977. 


Rude, Carolyn D. Technical Editing. Belmont, CA: Wadsworth Publishing 
Company, 1991. 


Technical Editing: Principles and Practices. Anthology Series No. 4. 
Washington, DC: Society for Technical Communication, 1975. 


Van Buren, Robert and Mary Fran Buehler. The Levels of Edit. JPL 
Publication 80-1. Pasadena, CA: Jet Propulsion Laboratory, 1980. (Available 
from the U.S. Government Printing Office) 


B.8 Usability 


Bond, Sandra J. “Protocol-Aided Revision: A Tool for Making Documents 
Usable,” Proceedings of the 1985 IBM Academic Information Systems University 
AEP Conference, June 1985: 327-334. 
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Craig, John S. “Approaches to Usability Testing and Design Strategies: An 
Annotated Bibliography.” Technical Communication 38(2), 1991: 1990-194. 


del Gado, Elisa, Robert C. Williges, Beverly H. Williges, and Dennis R. Wixon, 
“An Evaluation of Critical Incidents for Software Documentation Design.” 
Proceedings of the Human Factors Society — 30th Annual Meeting, 1986: 
19-23. 


Dillman, D.A. Mail and Telephone Surveys: The Total Design Method. John 
Wiley & Sons, 1978. 


Fern, Edward F., “The Use of Focus Groups for Idea Generation: The Effects 
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B.9.1 Online Help 


e Using VAX DOCUMENT to create help: VAX DOCUMENT Using Doctypes 
and Related Tags, available through your regular ordering channels and on 
the OpenVMS online documentation CD-ROM 


e Creating OpenVMS Help: VMS Librarian Utility Manual, available 
through your regular ordering channels and on the OpenVMS online 
documentation CD-ROM 


B.9.2 Bookreader Books 
¢ Using Bookreader, available on the OpenVMS and ULTRIX online 
documentation CD-ROMs 


° Managing a Bookreader Library, available on the OpenVMS and ULTRIX | 
online documentation CD-ROMs 


¢ Guidelines for coding Bookreader files with VAX DOCUMENT: 


— VAX DOCUMENT Producing Online and Printed Documentation, 
available through your regular ordering channels and on the OpenVMS 
online documentation CD-ROM 
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VAX DOCUMENT Using Doctypes and Related Tags, available 


through your regular ordering channels and on the OpenVMS online 
documentation CD-ROM 


Guidelines for coding Bookreader files with the DECwrite™ document 
processing application: 


- DECuwrite User’s Guide, available through your regular ordering 
channels or on the OpenVMS online documentation CD-ROM 


B.10 Production and Manufacturing 


Pocket Pal: A Graphic Arts Production Handbook. NY: International Paper 
Company, latest edition. 


Skillin, Marjorie E. Words into Type. Third edition. Englewood Cliffs, NJ: 
Prentice-Hall, Inc., 1974. 


White, Jan V. Editing by design: A guide to effective word-and-picture 
communication for editors and designers. NY: R.R. Bowker Company, 1982. 


B.11 Industry Standards 


Cargill, Carl F. Information Technology Standardization: Theory, Process, and 
Organizations. Bedford, MA: Digital Press, 1989. 


B.12 Engineering Process 


Corporate User Information Products. The Digital Guide to Developing 
Software. Bedford, MA: Digital Press, 1991. 
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Glossary 


This glossary defines new and unfamiliar terms used throughout the guide. 


acceptable ratio for success 

In usability studies, the percentage of tests that must be successful in order for 
the information to meet the usability goals. 

assembly sheet 


A document that indicates the following information about a component to the 
supplier: 


¢ Total page count and collation sequence of all elements 

e Specific pages requiring special treatment, such as the use of different 
inks, screens, halftones, and hand assembly 

authority list 

A record of the correct form of potential index entries, noting correct 

capitalization, plural forms, and preferred terms. 

base level 


A logical product unit composed of modules that meet a predefined level of 
usability. Engineering groups include the dates when base levels are completed 
in their product plans. 


binding method 
The method by which separate pages are gathered and held together. 


blue line 
See salt print. 
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CALS 


Computer-Aided Acquisition and Logistics Support. An initiative by the 
U.S. Department of Defense that specifies standards designed to facilitate 
the interchange of data in digital form between defense contractors and the 
Department of Defense. 


camera-ready copy (CRC) 


Artwork and final copy ready to be photographed for reproduction without 
further alteration. Repro proofs and mechanicals make up the camera-ready 
copy. 


See also mechanicals, repro proofs. 


CD-ROM 


Compact Disc Read-Only Memory. A small, compact disc with much greater 
storage capacity than magnetic media. The CD-ROM is read by laser rather 
than by magnetic heads. 


chunk 


The smallest unit of information that the Bookreader can access for display in 
a window. Information is grouped according to what the user needs to know. 
For example, sections, formal figures, tables, examples, and paragraphs are 
chunks. 


See also topic. 


click 

In the DECwindows environment, to press and release a mouse button, as in 
Click MB1. 

click on 

In the DECwindows environment, to press and release a mouse button when 
the pointer is positioned on an active object. Use click on for operations and 
selections you make with a pointing device. 

close-ended question 


A question for which answers are predefined. Test participants choose one or 
more of the supplied answers. 


Contrast with open-ended question. 
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color and screen markup copy 


An exact copy of the repro proof pages requiring multiple colors and screens, 
which indicates the location and color of inks and screens to the supplier. Also 
known as a color dummy. 


component 
A collection of information modules into a larger entity, such as a book or CBI. 


See also module. 


compound document 


An information component containing both text and image data. 


Computer-Aided Acquisition and Logistics Support 
See CALS. 


conceptual information 


A type of user information that describes the product environment and gives 
users the context they need for using the product. 


ConDist 


Common term for the CD-ROM used to distribute software products. The term 
is derived from the phrase consolidated distribution. In fact, both the software 
and the online documentation discs are the result of consolidated distribution, 
but the term ConDist has come to be associated with only the software disc. 


See also OLD. 


contextual inquiry 


An interviewing method that involves questioning and listening to users as 
they perform tasks in their normal work environment. 


See also structured interview. 


corner stapling 


A style of binding in which a wire staple is passed through the upper left 
corner of sheets of paper to hold them together. 


critical incident test 


A method of obtaining a user’s description of a successful or unsuccessful 
experience with either a product or its user information. 
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crop marks 


The lines drawn on a photograph or illustration to indicate where the image 
should be trimmed to remove extraneous areas. 


cross-reference 

An instruction that directs the user to more detailed or related information. 
For example, a See also cross-reference in an index directs the user to a related 
topic. 

customer glossary 


A collection of terms and definitions of company-specific, technical, or 
application-specific terms whose meanings may not be familiar to the user. A 
customer glossary is usually placed in the back matter of a component, after 
the appendixes and before the index. 


Contrast with project glossary. 


demand printing 
The printing of a component only when there is a requirement (demand) for it. 


design cue 


A typographic change or the use of color that reinforces a structural 
navigational cue or differentiates elements within text. For example, design 
cues often distinguish examples from text or point to the definition of a term in 
text. 


documentation map 
See information road map. 


drag 


In the DECwindows environment, to press and hold a mouse button, move the 
mouse, and then release the button when the pointer is in the position you 
want. 


film master 


A positive or negative image of the camera-ready copy that is produced by the 
film supplier and matches the camera-ready copy exactly, both in content and 
quality. 
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film master proof 


A preprint review copy of a document made from stripped-up film negatives. 
Also known as a printer’s proof. 


See also integral proof, overlay proof, salt print. 


film supplier 
The company responsible for producing the film masters. 


Contrast with print supplier. 


focus group 


A user group discussion guided by a trained meeting facilitator to gather 
information and opinions about a product or its user information. 


formal text element 


An entity or structure within text, such as a table or figure, that has a title 
and, optionally, a number. Formal text elements are always listed in a table of 
contents. 


formal usability edit 


A usability study in which a participant uses the product information to 
perform a task while an observer notes any successes or problems the user has 
in performing the task. 


See also informal usability edit, performance test. 


granularity 


The depth of information included in one topic. In Bookreader context, 
chapters and first-level sections are typically topics. However, depending on 
your authoring tool, you can increase or decrease the granularity to include 
more or less information in a topic. Generally, topics are no less than one 
quarter of a screen and no more than five screens long. 


graphics library 


Collections of graphics files that are organized to promote consistency in 
graphics and to save users from recreating commonly used images. 


hotspot 

In online information, the text of a cross-reference, which, when activated with 
the pointing device, displays a figure, table, or example in a separate window. 
A hotspot has a box around it; users can control whether the box is always 
visible or visible only when they move the mouse over the hotspot. 
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house style 


The set of rules that define an organization’s or company’s use of mechanics 
(spelling, capitalization, punctuation, and so on). The house style may also 
prescribe formatting conventions. For example, The Digital Style Guide defines 
the house style for Digital technical information. 


hypermedia 


A type of online information in which users access a range of information in a 
nonlinear way through linked networks of connected information. In the ideal 
system, users define their own connections between modules of information, 
which may take different forms, from traditional text and graphics to full color 
animated videos with sound. 


icon 
A simplified pictorial representation of an idea, a situation, or an object. For 
example, a clock face is often used to mean wait. 


informal text element 


An entity or structure within text, such as a table or figure, that does not have 
a title or number. 


Contrast with formal text element. 


informal usability edit 


A usability study in which a participant uses the product information to 
perform a task and notes successes or problems by annotating the information 
according to a predefined coding scheme. 


See also formal usability edit, performance test. 


information architecture 


A description of the principles of organizing information components into 
coherent information sets. 


information plan 


A plan that identifies the scope and contents of a user information project, 
including the staffing plans, resource needs, and project schedule. The final 
information plan is an agreement between the information group and funding 
group about how the product will be documented. Depending on the size 

of the project, the information plan may include production and packaging 
information, or there is a separate production and packaging plan. 
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information road map 


A navigational cue, usually in graphic form, that shows users the paths they 
may take to learn about a product and use the information component or set. 


information set 
The package of online, integrated, and hardcopy information about a product. 


integral proof 


A type of film master proof used for documents with four-color process printing. 
An integral proof is made by exposing separated four-color process negatives 
onto a special substrate material that gives a facsimile of four-color process 
printing. 


Compare with overlay proof, salt print. 


internationlization 


The process of producing a product for worldwide distribution, from the 
planning stages (influencing product requirements) through product 
localization. 


See also localization, translation. 


Likert scale 
A type of close-ended question in which test participants are asked to respond 
to a statement by marking one of five degrees of agreement: strongly agree, 
agree, neither agree nor disagree, disagree, strongly disagree. 

localization 


The process of adapting a product to a local market. Localization may include 
translation of parts of the user interface or user information. _ 


locator 


The page numbers in an index entry. 


logging 
The process of recording the use of a product or its user information. You can 
use software, audiotape, videotape, or a user’s written diary to record use. 


macro 


A command that requests an editor or language processor to generate text or a 
predefined set of instructions. 
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manpage 
See reference page. 


manufacturing 


The process of replicating and distributing a product or product information; 
the group responsible for replicating and distributing a product or product 
information. 


measurement criteria 
A description in a usability testing plan that specifies how you will determine 
whether or not the information being tested meets its usability goals. 


mechanicals 


Camera-ready pasteup assembly of all type and design elements, arranged in 
exact position and containing specific instructions for the supplier for final 
reproduction. 


module 


A small, discrete section of information about a single topic. 


mouse 


A type of pointing device used with windowing systems. Mouse is acceptable as 
a generic term for any pointing device used with a windowing system if you do 
not need to distinguish between the different types of pointing devices. 


navigational cues 


Elements of information designed specifically to help users easily find 
the information they need. Examples include tables of contents, indexes, 
information road maps, and running heads and feet. 


See also design cue, structural cue. 


nongoals 


In an information plan, tasks or deliverables that you might be expected to 
complete but that you do not plan to cover (for example, for lack of time or 
resources or because there are tasks with higher priorities). 
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OLD 


Common term for the CD-ROM used to distribute online books to be read 
using the DECwindows Bookreader application. The term is derived from the 
phrase online documentation. The term ConDist is often used to refer to the 
CD-ROM used to distribute software. In fact, both the software and the online 
documentation discs are the result of consolidated distribution. 


online book 
A book stored on a CD-ROM and viewed on a workstation or terminal. 


online information 


Any material in text or graphic form that users can display on their 
workstation or terminal screens. Online information can take several forms: 


e Context-sensitive information built into the user interface 
e Different varieties of reference information 
e Training modules and computer-based instruction 


¢ Books 


open-ended question 


A question for which answers are not predefined. Test participants fill in their 
own answers. 


Contrast with close-ended question. 


overlay proof 


A type of film master proof used to show the color separations of a book to be 
printed using three or more flat PMS ink colors. The proof is made by exposing 
light through stripped-up negatives onto light-sensitive, colored film gels that 
record the exact image on the negatives. 


Compare with integral proof, salt print. 


perfect binding 


A binding style in which all pages are trimmed at the binding edge and held 
together by glue. 


performance objective 


A statement in a usability testing plan that describes what you want users to 
be able to do with the information being tested. 
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performance test 

A test that requires a participant to perform a realistic set of tasks using 
the product and information. An observer might note data such as the time 
the user took to complete the tasks and the errors that occurred during task 
completion. 

point of entry 


In an index, the topic heading or primary entry for a given statement or 
concept. 


See also primary index entry. 


pop-up window 

A separate window that displays a graphic image. Users display pop-up 
windows by using the pointing device to activate a hotspot in text or by 
clicking on a formal table, figure, or example in the table of contents. 
primary index entry 


The word or phrase that indicates the main topic of an entry in an index. 

See also secondary index entry. 

printer’s proof 

See film master proof. 

print specification 

A work order that provides a set of manufacturing instructions to the supplier. 


print supplier 


The company responsible for reproducing multiple hard copies of user 
information. 


Contrast with film supplier. 


product 


An item to be used by a certain set of users. A product may be hardware, 
software, an integrated system, a process, standard, or conceptual information. 
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project glossary 


A collection of terms and definitions of company-specific, technical, or 
application-specific terms developed and used by the information and project 
team members to ensure consistent terminology use. 


Contrast with customer glossary. 


protocol 


In usability studies, the transcription of a testing session in which participants 
talk about a task while they perform the task or use the product information. 


protocol-aided revision 


A usability study in which a test participant, usually in a laboratory setting, is 
asked to perform a task and talk aloud while completing the task or using the 
product information. 


questionnaire 


A set of questions that can be sent to or used in telephone or face-to-face 
interviews with usability study participants. 


read and locate test 


A usability study in which participants try to find information in the 
component that answers particular questions. The success of the test depends 
on the users’ finding both the correct answers and the correct answers in the 
correct place. 


recto/verso page layout sheet 


A set of page-positioning instructions for the supplier, showing the general 
design of both right (recto) and left (verso) pages. The layout sheet includes 
trim marks, an identified marking point (like the page number), the component 
title, and the component part number. Also known as a matte or printer’s 
dummy. 


reference information 


A type of user information that gives details about particular entities in 

the product, explaining how they are used, restrictions on their use, their 
component parts, and other details that help the user make the fullest use of 
the product. 
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reference page 


Information that describes one command or facility from the UNIX 
environment, such as a system call or library routine. Reference pages may be 
in hardcopy or online form. Also known as a manpage. 


registered trademark 


A trademark that is registered with the United States Patent and Trademark 
Office. A registered trademark is identified by the ® symbol. Do not use the ® 
symbol with Digital trademarks. 


registration marks 


Crosses or other symbols applied to original copy before photography. 
Registration marks are used for positioning negatives in register or for 
registering two or more colors or screens in process printing. 


reproduction package 


The package of materials from which film masters are made. The reproduction 
package consists of the following items: 


¢ Repro proofs 

¢ Mechanicals 

¢ Color and screen markup copy 

¢ Assembly sheet 

e¢ Print specification 

e Waiver, if needed 

¢ Sample page layout (recto/verso page layout sheet) 


Also known as a repro package, repro pack. 
repro proofs 
Finalized type printed on quality paper for use as camera-ready copy. 


ring binding 


A binding style in which pages are drilled and then kept in binders with metal 
ring mechanisms. 


running foot 


A string of text at the bottom of a page that serves as a navigational cue. In 
Digital books, running feet most often identify the title of a chapter. 
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running head 


A string of text at the top of a page that serves as a navigational cue. In 
Digital books, running heads most often identify the contents of a section. 


saddle stitching 


A binding style in which pages are fastened together by wire stapling through 
the middle folds of the sheets. 


salt print 


A type of film master proof used for documents with one or two flat ink 

colors. A salt print is made from stripped-up negatives to show all text and 
graphic elements to be printed. Salt prints are made by exposing a light 
source through the film negatives or positives, which duplicates the image that 
appears on the film. Salt prints are also known as blue lines, blues, blueprints, 
Dylux copies, ozalid copies, silver prints. 


Compare with integral proof, overlay proof. 


script 
The prepared set of instructions and questions that you use in an interview 
with a user. 


secondary index entry 


In an index, the words or phrases that further specify or clarify a particular 
aspect of the topic being indexed. The secondary index entry modifies the 
primary index entry. 


service mark 


Any word, symbol, design, or combination of those items that is used by service 
providers to distinguish their services from the services provided by other 
companies. Use the SM symbol to identify service marks. For example, the 
DECsite®™ mark is a Digital service mark. 


See also trademark. 
spine insert 
Information printed on card stock for insertion into the spine insert holder 


located on the spine of a ring binder. Spine inserts identify the user 
information located in the binder. 
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structural cue 


A navigational aid that provides an explicit pointer to the organization and 
content of the user information. Tables of contents, information road maps, 
and indexes are examples of structural cues. 


structured interview 


An interview conducted with the aid of a prepared set of questions or a script. 
Interviews may be held face to face or over the telephone. 


style sheet 


A list of project-specific rules that supplements the organization’s style rules. 
A style sheet usually covers the following types of information: 


e Spelling, capitalization, and punctuation of specific words and phrases 
¢ Abbreviations and acronyms 

¢ Bibliographic conventions 

¢ Footnote information 

¢ Numbers 

¢ Symbols 

e Typographic conventions 


See also house style, word list. 


summary test 

A usability study in which a participant summarizes the meaning of a short 
passage. Responses are compared with a summary previously prepared by the 
writer of the passage. 

supplier 


A company contracted to perform a task, such as making film masters. Also 
known as a vendor. 


See also film supplier, print supplier. 


symbolic name 


The logical name that you assign to a text entity, such as a chapter, section, or 
formal figure. When you refer to the entity, you use the symbolic name rather 
than the entity’s title. 


See also formal text element. 
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tabbed divider 


Pages of a component printed on heavy stock to separate parts of the 
component. The tabbed extensions make it easier to locate the different parts. 


task analysis 


The gathering of information about the tasks that a user performs. You may 
gather data for a task analysis through questionnaires, interviews, and other 
testing methods as well as through reading project planning documents. 


task-oriented information 


A type of user information that explains how the user can accomplish a 
particular task using a procedure or series of procedures. 


topic 
Generally, a cohesive, self-contained unit of information that describes a 
complete task, concept, or feature. 


In the Bookreader context, one or more chunks of information displayed on 
successive screens. Typically, chapters and first-level heads are topics. 


See also chunk. 


topic/audience matrix 


A grid that maps topics to be discussed in the user information to the different 
audiences for the product. The matrix concept was developed by Edmond H. 
Weiss. The matrix is a tool that you can use to organize your product and 
audience research. 


trademark 


Any word, symbol, design, or combination of those items that is used by 
manufacturers to distinguish their products from those of competitors. An 
unregistered trademark is identified by the ™ symbol. For example, the 
DECwindows mark is a Digital trademark for a user interface. A registered 
trademark is identified by the ® symbol. For example, POSTSCRIPT is a 
registered trademark of Adobe Systems, Inc. 


See also registered trademark, service mark. 


translation 


The process of changing text from one natural language to another, preserving 
the meaning of the original language. 


See also localization. 
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trim marks 
Marks placed on copy to indicate the edge of a page. 


trim size 

The finished size of a component after it has been bound or folded and trimmed 
on the top, bottom, and right to meet specifications. 

tutorial 

A type of task-oriented information intended for users unfamiliar with the 
product. Tutorials guide the users through a set of basic procedures using 
predesigned examples. 

update package 


A collection of loose replacement pages containing changes to information in a 
ring-bound book. Customers insert the new pages into their binders. Updates 
may be used when 30 percent or less of the book’s page count changes. The 
update package includes: 


¢ Update notice page with a part number and instructions for inserting the 
replacement pages 


e New title page 

¢ New copyright page 

¢ New table of contents 

¢ Replacement pages with new or revised material marked 
e New index 

usability edit 


A usability study in which participants make specific notes when they have 
probblems (or success) using the user information with the product to perform 
tasks. There are two types of usability edits: formal and informal. 


See also formal usability edit, informal usability edit. 


usability study 


Any test that determines whether information is easy to find, easy to 
understand, and complete enough to help a user complete a set of tasks. 
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user information 


Any material, in printed or electronic form, that does one or more of the 
following: 


e Trains users to use a product 


e Describes the features of the product in a way that users can readily find 
the information they need to complete their tasks 


¢ Shows users how to make the most efficient use of product features 


¢ Provides conceptual material that helps the user understand how the 
product works with other products 


See also information set. 


user information team 


The individuals responsible for creating the user information for a product. 
The information team contains individuals who are responsible for writing, 
editing, graphic design, and production. 


vendor 

See supplier. 

wire-O binding 

A binding style in which a continuous double series of wire loops runs through 


punched slots along the binding edge of a component. 


word list 


An alphabetized list citing the accepted spelling for technical terms and terms 
frequently misspelled or misused. Word lists may also contain brief notes 
about usage. Word lists often apply to more than one product. 


See also style sheet. 
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List of Trademarks 


Bookreader, CDA, DEC, DECUS, DECwindows, DECwrite, Digital, 
Digital Press, EDT, LinkWorks, OpenVMS, ULTRIX, ULTRIX 
Worksystem Software, VAX, VAX DOCUMENT, VAX Notes, VMS, 
XUI, and the DIGITAL logo are trademarks of Digital Equipment 
Corporation. DECmailer, DECservice, DECsite, and Electronic Store 
are service marks of Digital Equipment Corporation. 


Information Mapping is a registered trademark of Information 
Resources, Inc. 


MS-DOS is a registered trademark of Microsoft Corporation. 
Motif, OSF, and OSF/1 are registered trademarks and Open 
Software Foundation is a trademark of the Open Software Founda- 


tion, Inc. 


PostScript is a registered trademark of Adobe Systems Incor- 
porated. 


SUN is a registered trademark of Sun Microsystems, Inc. 


UNIX is a registered trademark of UNIX System Laboratories, Inc. 


— (Minus sign) in index entries, 178 
; (Semicolon) with glossary definitions, 163 
/ (Slash) in index entries, 178 


A 


Abbreviations, 154 
glossaries and, 161 
indexing, 178, 179 
style sheet and, 156 
word list and, 158 
Abstract language, 155 
Access aids 
See Navigational cues 
Accessibility 
See also Navigational cues 
editing for, 110, 112 
goal of user information, 4 
indexes and, 165 
online books, 128 
Accounts needed, listing in information plan, 
83 
Accuracy 
editing for, 111, 112 
field test reviews and, 123 
glossary entries, 160 
goal of user information, 4 
technical reviewers and, 109 
user reviewers and, 114 
Acronyms, 154 
glossaries and, 160, 161 
glossary definitions and, 161 
indexing, 172,179 
style sheet and, 156 
word list and, 158 


Index 


Adjectives 
glossary definitions of, 161 
primary index entries, 174 
secondary index entries, 181 
Adverbs, as primary index entries, 174 
Alphabetizing 
glossary entries, 160 
index entries, 172 
Alpha testing 


See Field tests 
See Field test updates 
ANSI standards, computer terminology, 268 
Antonyms in glossary, 164 
Appropriateness 
editing for, 103, 110 to 113 
goal of user information, 4 
technical reviewers and, 109 
terminology and, 153 
user reviewers and, 114 
Archiving, 149 
information plan, 149 
post-project report, 145, 149 
source files, 149 
user feedback, 149 
Articles, in secondary index entries, 182 
Artwork 
checking online, 254 
DECwindows Motif Help and, 201 
editing, 112,113 
indexing, 172,173 
information plan milestones, 85, 89 
in production and packaging plan, 94 
in review drafts, 107 
mechanicals, 136, 260 
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Artwork (cont’d) 
online books, 128 


submission to internationalization group, 


84 

tools, 93 
Assembly sheets 

purpose of, 136 

quality assurance checklist, 262 
Audience 

defined, 21 

editing for, 110 

telephone interview considerations, 229 
Audience description, in information plan, 

72, 74 

Audience research 

See also Research 

information needed, 22 

modular design and, 37 

quality assurance checklist, 248 

sources for, 25 
Audience/topic matrixes 

defined, 45 

developing, 45, 46, 47 
Authority lists 

creating for index, 168 

sorting, 170 


Base levels 
determining order of writing, 102 
master information plan milestones, 83 
scheduling and, 65 
Beta testing 
See Field tests 
See Field test updates 
Bibliographic conventions, style sheet and, 
156 
Binding methods 
in print specification, 136 
in production and packaging plan, 94 
Blocks, number of, in production and 
packaging plan, 94 
Blueprints 
See Film master proofs 
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Blues 
See Film master proofs 
Boldface type, 213 
Bookreader, 194 
See also CD-ROMs 
See also Online books 
bibliography, 271 
chunks of information, 196 
concepts, 195 
features, 194 
hotspots, 197 
hypermedia capabilities, 207 
libraries, managing, 271 
pop-up windows, 197 
required elements, 195 
topics, 196 
using, 271 
Book titles 
listing in information plan, 73 
master indexes and, 189 
Bottom-up design, 41 
Budgeting, 68 
information plan and, 82 
Business plan, 26 
Buttons, online help for, 199 
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Camera-ready copy 


See Mechanicals 
See Repro proofs 
Capitalization 
editing for, 110, 112 
glossary entries, 160 
primary index entries, 180 
secondary index entries, 183 
style sheet and, 156 
Capital letters, for emphasis, 213 
Case study 
audience overview, 44 
cross-product information, 50, 57 
delivery media, 54, 57 
hardcopy information, 50, 54, 57 
multiplatform issues, 51 
online information, 54, 57 


Case study (cont'd) 
organizing information by task, 48 
organizing information by type, 48 
product overview, 43 
reference pages, 52 
refining design, 54, 57 
standards compliance, 52 
testing design, 53 
topic/audience matrixes, 45, 46, 47 
Catch-all phrases, 155 
Cautions, indexing, 169 
CD-ROMs 
See also Bookreader 
See also Online books 
online documentation disc release 
schedules, 138 
online documentation discs, 138 
submission process for online books, 138 
Changes 
marking in drafts, 107 
to information plan after signoff, 64 
to schedule, 66 
Changes in user information environment, 
10 
customizable information, 14 
delivery media, 12 
expert solutions, 12 
hardcopy page counts, 13 
hypermedia, 207 
internationalization, 12 
modular information, 14 
multiple platforms, 11 
open systems, 11,12 
publishing tools, 13 
strategic directions, 11 
Check copies 
See Film master proofs 


Checklists 

See Quality assurance checklists 
Chunks, in online information, 196 
Clarity 

editing for, 103, 111 to 113 

goal of user information, 4 

terminology and, 154 

user reviewers and, 114 


Client satisfaction surveys, 145 to 147 
advantages, 145 
archiving, 149 
disadvantages, 145 
improving results, 146 
sample, 145 
Close-ended questions, 225 
Closure of project, 141 
Code freeze, 89 
master information plan milestone, 83 
Color 
as a navigational cue, 213 
in print specification, 136 
in production and packaging plan, 94 
online books and, 127 
Color and screen markup copy, 136 
quality assurance checklist, 261 
Commands, indexing, 172, 178 
Communication, evaluating at post-project 
review meeting, 144 
Compare with cross-references in glossary, 
164 
Competitive literature, 31 
corporate libraries, 31 
in information plan, 72 
trademark information and, 244 
Completeness 
editing for, 111,112, 113 
goal of user information, 4 
Component information plans 
See also Information plans 
defined, 62 
milestones, 83 
Components 
combining information types, 39 
defined, 3 
describing in information plan, 73, 74 
final signoff, 129 
final signoff milestones, 89 
readiness for manufacturing, 83 
Compound phrases, indexing, 174, 176 
Computer dictionaries, 268 
Computer glossaries, 268 
Concepts, indexing, 172 
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Conceptual information, 38 
hardware information and, 39 
information architecture and, 41 
software information and, 48 

Concrete language, 155 

Conditions for usability studies, 217 

Confidential information, labeling 

information plan, 70 
Conjunctions, in secondary index entries, 
182 

Consistency 
conventions tables, 154 
editing for, 111, 112, 113 
glossary and index entries, 179 
index conventions, 166 
modular information and, 15 
related index entries, 182 
terminology and, 153, 154 

Consortia, planning submissions to, 33 

Context-sensitive help, 199 

Contextual inquiry, 236 to 238 
advance notice for, 237 
benefits, 240 
process, 237 

Contextual interviews 
See Contextual inquiry 

Contingency plans, information plan 

description, 92 
Contrast with cross-references in glossary, 
164 

Conventions 
bibliographic, 156 
editing for, 112 
file names, 76 
footnotes, 156 
index entries, 166 
online books, 127 
style sheets, 156 
typographic, 156 

Conventions tables, 154 

Copy editing, 7, 110 

Copyright pages, for information plans, 70 

Corporate libraries 
research tool, 31 
trademark information and, 243 
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Costs 
estimating in information plan, 68, 82 


evaluating at post-project review meeting, 


143 
Courses 
See also Training 
attending as research tool, 31 
requirements in information plan, 83 
Cover letters 
for formal document inspection, 119 
for formal review, 105 
for review meeting, 116 
Covers 
in print specifications, 136 
in production and packaging plan, 94 
Creative block, 102 
Critical incident tests, 238, 241 
Cross-product information 
case study and, 50, 57 
defined, 5 
information architecture and, 41, 48 
information types and, 38 
word lists and, 158 
Cross-references 
editing, 112 
emphasizing, 163, 186 
glossary, 162, 163 
Compare with, 164 
Contrast with, 164 
See, 164 
See also, 164 
hotspots, 197, 211 
index, 167,178 
general guidelines, 185 
page numbers with, 185 
See, 167, 185, 186 
See also, 167, 185, 188 
synonyms, 176,177 
linking online information, 201, 207 
navigational cues, 211 
online books, 127, 254 
Culture-specific language, 155 
Customer courses, as research tool, 31 
Customer glossaries 


See also Glossaries 


Customer glossaries (cont'd) 
compared to project glossaries, 159 
defined, 158 
Customer problem reports, 30, 92, 149 
Customer questionnaires 
See Questionnaires 
Customers 
nondisclosure agreements and, 219 
usability study participants, 219 
user groups, 30 
Customer support groups 
as information resource, 30 
as user reviewers, 114 
Customer visits 
See also Usability studies 
field test sites, 125 
research information source, 29 
Customizing information 
modular information and, 15 
strategic directions, 14 
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Dates, form of for information plan 
milestones, 85 
DCL Help, 202 
DECwindows Motif Help, 200 
advantages, 201 
comparison with DECwindows Help, 201 
hypermedia capabilities, 207 
DECwindows XUI Help, 199 
comparison with DECwindows Motif Help, 
201 
guidelines, 200 
INCLUDE command and, 199 
structure of, 199 
Define stage, user information process, 19, 
20 
information plan milestones, 85 
researching, 21 
Deliver stage, user information process, 19, 
20 
final production, 133 
information plan milestones, 87, 90 
project closure, 141 


Delivery media, 12, 41, 49 
case study design and, 54, 57 
in production and packaging plan, 95 
listing in information plan, 73 
Dependencies, information plan description, 
91 
Design documents, 26 
Design elements 
editing for, 113 
online books, 127 
Design navigational cues, 212, 213 
Design process 
bottom-up, 41 
case study, 43 
steps in, 35 
top-down, 41 
topic/audience matrixes, 45 to 47 
Design stage, user information process, 19, 
20 
information plan milestones, 85 
steps in process, 35 
structuring information, 35 
writing information plan, 61 
Developmental editing, 7 
Development plan, 26 
Develop stage, user information process, 19, 


draft process, 99 
information plan milestones, 85 
review process, 99 
Dialog boxes, online help for, 199 
Dictionaries, 265, 268 
Distribution services, 139 
Doctypes, in production and packaging plan, 
93 
Documentation maps, 211 


Documentation plans 
See Information plans 
Documentation project leader 


See Project leader, information 
Document inspections, formal, 117 

inspection team members, 118 

inspectors, 118 

moderator, 118 
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Document inspections, formal (cont'd) 


problem categories, 119 
process, 121 

reader, 118 

recorder, 118 

writer, 119 


Draft process 


art development, 85 

art submission, 89 

beginning first draft, 101 
creative block, 102 

information plan milestones, 85 
steps in, 100 

usability studies and, 215 


Duplication services, 139 


Editing 


See also Editors 

See also Final production 
accessibility, 110, 112 
accuracy, 111, 112 
appropriateness, 103, 110 to 113 
artwork, 112, 113 

audience definition, 110 
bibliography, 265, 266, 269 
clarity, 103, 111 to 113 
completeness, 111, 112, 113 
consistency, 111, 112,113 
conventions, 112 

copy editing, 7, 110 
cross-references, 112 

design elements, 113 
developmental editing, 7 
during informal reviews, 103 
editorial review elements, 110 
examples, 112 

final signoff, 129 

first draft, 110 

following standards, 111 
formal review process and, 109 
format, 112, 113 

index entries, 113, 191 

index review, 88, 104 
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Editing (cont’d) 
information plan signoff, 70 
internationalization, 113 
level of detail, 103 
method of presentation, 103 
navigational cues, 113 
online books, 128 
online information, 113 
organizational, 103, 110 
procedures, 111 
purpose of information, 110 
redundancy, 111, 112 
second draft, 110 
signoff draft, 110 
style, 112 
substantive editing, 7, 110 
table of contents, 112 
tables, 112 
titles, 112 
tone, 110, 112 
trademark use, 112 
types of, 110 
usability, 112, 113 
Editorial reviewers 
See also Editing 
in information plan, 79 
responsibilities, 109 
Editors 
See also Editing 


See also Final production 
as primary editorial reviewers, 109 
creating style sheets, 156, 157 
creating word lists, 156 
formal review process and, 109 
information plan and, 62 
post-project review meeting and, 142 
role in user information team, 6 
EDMS, 137 
Electronic Documentation Mastering 
Standard 
See EDMS 
Electronic submissions, 137 
in production and packaging plan, 93 
Element names for reference pages, 206 


Emphasis 

glossary cross-references, 163, 164 

index cross-references, 186 

navigational cue, 213 

online books and, 127 
Employees, as usability study participants, 

219 

Engineering design documents, 26 
Engineering development plan, 26 
Engineering process, 19, 99 

See also Phase Review Process 

bibliography for, 272 
Engineering project leader 

See Project leader, technical 
Engineering team 

See also Technical reviewers 

attending meetings of, 28 

design documents, 26 

final signoff, 129 

information plan signoff, 70 

post-project review meeting, 142 

product specifications, 26 

project plans, 26 

working with, 27, 102 
Equipment needs, in information plan, 83 
Error messages, indexing, 174 
Examples 

editing, 112 

indexing, 172,173 

in pop-up windows, 197 

online books, 127 
External publications 

in information plan, 74 
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Field test administrator 
as user reviewer, 114 
responsibilities, 124 
submitting information to, 87 
submitting updates to, 88 

Field test reviews, 99, 104 
improving results from, 124 
incorporating comments, 126 
indexes, 88 


Field test reviews (cont’d) 
information plan milestones, 88 
master information plan milestones, 83 
purpose of, 123 
questionnaires, 125 
telephone interviews, 125 

Field tests 
beginning of, 87 
effect on schedule, 66 
external, 65 
information-only, 125 
internal, 65 
online information review, 87 
scheduling and, 65 
submission to copy center, 86 

Field test training, 124 

Field test updates 
beginning, 88 
scheduling and, 65 
submission to copy center, 88 
submitting online information, 88 

Figures 
See also Artwork 
checking online, 254 
indexing, 172,173 
in pop-up windows, 197 
online books, 127 

File extensions, listing in information plan, 

73 

File maintenance tools, 82, 95 

File naming conventions 
guidelines, 76 
in information plan, 76 
internationalization and, 77 

File suffixes, listing in information plan, 73 

File types, listing in information plan, 73 

Film master proofs 
defined, 138 
print specification and, 136 
proofing considerations, 138 
quality assurance checklist, 263 

Final information plans, 63 


See also Information plans 
Final production 


See also Production and packaging plans 
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Final production (cont’d) 


assembly sheets, 136, 262 

beginning, 90 

color and screen markup copy, 136, 261 

component information plan milestones, 
84 

defined, 133 


delivery of reproduction package, 90, 134 


effect on schedule, 66 

electronic submissions, 137 

hardcopy, 134 

information plan and, 70 

master copy, 135 

mechanicals, 136, 260 

preparing for, 133, 136 

print specifications, 136, 261 

procedures for, 133 to 138 

process flow, 134 

proofreading, 135 

recto/verso layout sheet, 137 

reproduction packages, 136, 137, 259 

repro proofs, 135, 259 

signoff, 137 

standards for, 135 

submitting artwork, 89 

submitting print specifications, 90 
Final signoff 

of information set, 129 

review, milestone for, 89 

sample form, 130 
First Customer Ship 

See Product shipment date 
First drafts 

beginning, 101 

indexes, 167 

milestones in information plan, 85 

online help, 128 

order of writing, 102 

review, 85, 86, 104 

substantive editing and, 110 
First Revenue Ship 

See Product shipment date 
Focus groups, 239, 242 
Footnotes 

checking online, 254 
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Footnotes (cont'd) 
conventions in style sheet, 156 
in pop-up windows, 197 
Formal document inspections 


See Document inspections, formal 
Formal reviews, 99 
compared with informal reviews, 104 
cover letter, 105 
distributing review copies, 108 
editing, types of, 110 
information plan milestones, 83, 85, 87 
list of reviewers, 105 
number of, 104 
preparing for, 104 
preparing review drafts, 107 
purpose of, 104 
review package, 108 
scheduling, 107 | 
signoff review milestones, 89 
update packages, 108 
Formal standards 
complying with, 12 
listing in information plan, 92 
Formal usability edits, 230 
benefits, 240 
process, 231 
Format 
editing for, 112,113 
in production and packaging plan, 93 
Front matter, online books, 127, 253 
FTn 
See Field test updates 
Functional specifications, 26 
Funding groups 
evaluating satisfaction of, 145 
final signoff, 129 
information plan signoff, 70 
post-project review meeting and, 142 
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Gerunds, as primary index entries, 174 
Glossaries 
See also Glossary cross-references 
See also Glossary entries 
circulating for review, 160 
computer, 268 
customer, 158, 159 
project, 158, 159 
translation team and, 155 
types of, 158, 159 
Glossary cross-references, 162, 163 


See also Glossaries 
See also Glossary entries 
Compare with, 164 
Contrast with, 164 
emphasizing, 163 
See, 164 
See also, 164 

Glossary entries 
See also Glossary cross-references 
abbreviations, 161 
acronyms, 161 
alphabetizing, 160 
antonyms, 164 
capitalizing, 160 
consistency with index entries, 179 
creating, 160, 162 
formatting, 160 
indexing, 174 
multiple definitions, 163 
ordering, 160 
parallelism, 161 
parts of, 160 
related terms, 164 
selecting, 160 
semicolons in definitions, 163 
synonyms, 162, 164 

Goals 
of information set, 74 
usability studies, defining, 217 
user information, 4 


Grammar, editing for, 110, 112 
Granularity 

editing for, 103 

index entries, 171, 177 

modules, 37 

online book topics, 127, 128, 196 
Graphic designers 

See also Artwork 

information plan and, 62 

post-project review meeting, 142 

role in user information team, 7 
Group interviews, 239, 242 
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Hardcopy information 
binding methods in production plan, 94 
case study design and, 50, 54, 57 
changing attitudes towards page counts, 
13 
cover types in production plan, 94 
final production, 134 
information types and, 41 
ink colors in production plan, 94 
kit descriptions in production plan, 95 
listing in information plan, 73 
page count in production plan, 94 
print specification submission, 90 
spines in production plan, 94 
submission methods in production plan, 
93 
tabbed dividers in production plan, 94 
trim size in production plan, 94 
Hardware, identifying in information plan, 
72, 83 
Hardware information 
information architecture example, 39 
organizing by information type, 39 
Headers 
See Section titles 
Help systems 
bibliography, 271 
DECwindows Motif Help, 200 
DECwindows XUI Help, 199 
OpenVMS Help, 202, 203 


Index 301 


Help systems (cont'd) 
reference pages, 205 
Hotspots, 197, 207 
checking, 253, 254 
DECwindows Motif Help and, 201 
navigational cues, 211 
online index entries, 254 
House style, 156 
Human factors 
See Usability 
Hypermedia, 206 
bibliography, 271 
combining with other online methods, 
207 
hotspots, 207 
linking topics, 207 


Icons 
margin icons, checking online, 254 
navigational cues, 212 


IEEE standards, computer terminology, 268 


IES standards, computer terminology, 268 
Illness, scheduling and, 67 
INCLUDE command, DECwindows XUI 
Help and, 199 
Index cross-references, 167, 178 
See also Index entries 
general guidelines, 185 
italic type and, 186 
page numbers with, 185 
See also cross-references, 167, 185, 188 
See cross-references, 167, 185, 186 
synonyms, 176,177 
Index entries, 166 
See also Index cross-references 
abbreviations, 178, 179 
acronyms, 172,179 
alphabetizing, 172 
cautions, 169 
commands, 172,178 
compound phrases, 174, 176 
concepts, 172 
consistency in, 182 
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Index entries (cont'd) 
consistency with glossary entries, 179 
consolidating, 184 
creating, 172,181 
defined terms, 173 
examples, 172,173 
figures, 172,173 
glossary entries as, 174 
keywords, 172,178 
locators, 166 
messages, 174 
mnemonics, 172 
notes, 169 
number of levels, 184 
numbers, 180 
online, checking, 254 
options, 172,178 
parameters, 172,178 
parts of, 166 
primary, 166, 172 
adjectives, 174 
adverbs, 174 
capitalization, 180 
compound phrases, 176 
nouns, 174 
number of locators, 181 
number of page references, 181 
plural forms, 180 
singular forms, 180 
verb phrases, 175 

procedures, 172 

qualifiers, 172,178 

related topics, 167, 185 

routines, 173, 178 

secondary, 166, 181 
adjectives, 181 
articles in, 182 
capitalization, 183 
conjunctions in, 182 
nouns, 181 
prepositions in, 181, 182 
verbs, 181 

section titles, 173 

selecting, 168, 172, 181 

standards, 173 
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switches, 172, 178 

symbols, 178, 180 

synonyms, 167,176,177 

tables, 173 

tasks, 168, 173,175 

terms, 169, 177 

tertiary, 184 

utilities, 173, 178 

warnings, 169 
Indexes 

See also Index cross-references 

See also Index entries 

analyzing topics, 171,177 

bibliography, 269 

characteristics, 165 

conventions for, 166 

creating, 167 to 192 

creating an authority list, 168 

editing, 113,191 

editorial review, 88, 104 

master, 189 

navigational cues, 210 

needed for Bookreader, 195 

online books, checking, 128, 198, 254 

online books and, 127, 185 

points of entry, 165 

purpose of, 165 

revising, 191 

selecting entries, 168, 172 

size of, 167,172 

when to develop, 167 
Individual information plans 

See Component information plans 
Industry standards 

bibliography, 272 

complying with, 12 

listing in information plan, 92 
Informal reviews, 99 

compared with formal reviews, 104 

editing, 103 

scheduling, 103 

working with technical experts, 103 
Informal usability edits, 231 

benefits, 240 
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process, 231 
Informational reviewers, of information plan, 
70, 79 
Information architecture 
defined, 39 
delivery media and, 41, 49 
hardware information example, 39 
organizing by delivery media, 41 
organizing by information type, 39, 41, 
48 
organizing by task, 39, 48 
relation with design and methodology, 41 
software information example, 48 
Information design 
bottom-up, 41 
case study, 43 
relation with architecture and 
methodology, 41 
top-down, 41 
Information freeze, 89 
Information Mapping methods, training, 267 
Information plans 
See also Production and packaging plans 
actual dates, 85 
archiving at end of project, 149 
artwork milestones, 85, 89 
as team effort, 62 
audience description, 74 
audience overview, 72 
budgeting, 68, 82 
changes after signoff, 64 
code freeze, 89 
comparing master and component, 83 
competitive literature analysis, 72 
component plans, 62 
contents, 70 
contingency plans, 92 
copyright page, 70 
critical project dates, 65, 83 
delivery media, 73 
dependencies, 91 
equipment needs, 83 
estimated dates, 85 
external publications, 74 
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Information plans (cont'd) Information plans (cont’d) 


field test milestones, 86, 87, 88 reference page descriptions, 75 

file naming conventions, 76, 77 reviewers, 70, 79 

final, 63, 64, 85 review meeting notification, 116 

final production milestones, 90 review process, 63 

final signoff milestones, 89 risks, 91, 92 

first draft review milestone, 85 schedules, 65, 66, 83 

goals of information set, 74 schedule slips, 92 

hardcopy information, 73 second draft review miletones, 87 

index edit milestone, 88 signoff, 63, 64, 85 

informational reviewers, 70 signoff reviewers, 70 

information freeze, 89 source file types, 73 

information set description, 73, 74 staffing, 67, 79 

installation guide milestones, 86 standards, 92 

internationalization, 77, 84 table of contents, 70 

internationalization contact templates information, 77 
responsibilities, 78 title page, 70 

localization, 77 tools information, 77, 82 

master plans, 62 translation, 77 

milestones, 65, 83 to 90, 251 translation coordinator responsibilities, 

nongoals, 74 78 

online book commitment dates, 84 usability testing plans and, 77, 217 

online book descriptions, 75 waivers, 92 

online book milestones, 84 when to write, 63 

online example description, 75 Information project leader 


online help description, 75 
online help freeze, 89 Information road maps, 211 

online information description, 73, 75 Tatsiniation Bets 

online information milestones, 87 defined, 3, 12 

outlines, 75 ; description in information plan, 74 
packaging information, 93 designing, 35 

Phase Review Process and, 61, 84 final signoff, 129 

Phase Review Process requirements, 64 goals in information plan, 74 
preliminary plans, 63, 64, 85 kitting, 95 

print specification milestones, 90 
product dependencies, 72 
production information, 93 
product overview, 72 

product shipment milestone, 90 
project leader role, 8, 62 

project maintenance, 92 


See Project leader, information 


outlines in information plan, 75 
summary in information plan, 73 
Information types, 38 
combining, 39 
hardcopy information and, 41 
hardware information and, 39 
, ; i : ; online information and, 41 
proprietary information classification, 70 organizing information by, 39, 41, 48 


purpose, 61, 62 ; software information and, 48 
quality assurance checklist, 251 Ink colors 


quality assurance milestones, 87, 90 color and screen markup copy, 136 
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Ink colors (cont’d) Interviews (cont'd) 


in print specification, 136 telephone, 227 to 230 
in production and packaging plan, 94 advance notice for, 228, 229 
Inspections, formal benefits, 239 


See Document inspections, formal guidelines, 228 


Inspectors for formal document inspections, quality ASSULBNCE checklist, 258 
118 training interviewers, 229 


ISO standards, importance of, 92 
Italic type, 213 
glossary cross-references, 163, 164 
index cross-references, 186 


Installation guides 
field test review milestones, 87, 88 
first draft review milestones, 86 
quality assurance milestones, 87, 90 
submission milestones, 84 

Integral proofs, 138 J 
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document inspections, 117 
informal reviews, 103 
peer reviews, 115 K 
review meetings, 116 

Internal users 
as usability study participants, 219 


Jargon, different senses of, 155 


Keywords, indexing, 172, 178 
Kitting structure 
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WeIVere and, 92 research tool, 31 
Internationalization group trademark information and, 243 
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group, 239, 242 online book indexes, 185 
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Logging usability study method, 238, 241 
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Manpages 
See Reference pages 
Manufacturing 
Bookreader books, 138 
CD-ROM books, 138 
delivery of reproduction package, 84, 90, 
134 
effect on schedule, 66 
electronic submissions, 137 
film master proofs, 138, 263 
project numbers in plans, 93 
readiness, milestone in master 
information plan, 83 
submission date, 65 
Manufacturing group 
as user reviewers, 114 
in production and packaging plan, 93, 95 
post-production work, 139 
post-project review meeting, 142 
Margin icons 
checking online, 254 
navigational cues, 212 
Marketing group, as user reviewers, 114 
Marketing requirements document, 26 
Master copies 
See Repro proofs 
Master indexes 
See also Indexes 
conventions, 189 
defined, 189 
guidelines, 189 
Master information plans 
See also Information plans 
defined, 62 
milestones in, 83 
Measurement criteria for usability studies, 
217 
Mechanicals, 136 
quality assurance checklist, 260 
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Media, listing in information plan, 73 
Menu items, online help for, 199 
Menus, online help for, 199 
Messages, indexing, 174 
Milestones, 65, 83 to 90 
actual dates, 85 
art submission, 85, 89 
code freeze, 89 
component information plans, 83 
estimated dates, 85 
field test beginning, 87 
field test review, 86 
field test updates, 88 
final component signoff, 89 
final production, 90 
first drafts, 85 
index edit, 88 
information freeze, 89 
information plan signoff, 85 
installation guides, 86 
internationalization, 84 
manufacturing delivery, 90 
master information plans, 83 
online books, 84 
online help freeze, 89 
online information, 87 
online information submission, 88 
Phase Review Process and, 84 
preliminary information plan available, 
85 
print date, 90 
print specification submission, 90 
product shipment date, 90 
quality assurance checklist, 251 
quality assurance submission, 87, 90 
reproduction package delivery, 90 
second draft review, 87 
testing online files, 84 
Minus signs, in index entries, 178 
Mnemonics, indexing, 172 
Moderators 
document inspection, 118 
peer review meetings, 115 
post-project review meeting, 144 


Modular information 
See also Modules 
advantages of, 14 
architecture and, 41 
case study, 43 
combining information types, 39 
consistency and, 15 
controlling redundancy, 15 
customizing, 15 
design and, 41 
design process, 35, 41 
information types, 38 
reuse, 14,15 
strategic directions, 14 
topic/audience matrixes, 45 to 47 
training courses, 267 
writing for online, 196 
Modules 
characteristics, 36 
conceptual, 38 
defined, 36 
granularity, 37 
identifying, 37 
information types, 38 
linking, 201, 207 
order of writing, 102 
reference, 38 
task-oriented, 38 
titles, as navigational cues, 210 
Multiplatform information, 11 
bibliography, 268 
case study and, 51 
Multiword phrases, indexing, 174, 176 
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Navigational cues, 209, 266 
color, 213 
cross-references, 211 
defined, 209 
design cues, 212 
editing, 113 
emphasis, 213 
hotspots, 197, 211 

checking, 253, 254 


Navigational cues (cont'd) 

hypermedia and, 207 

index entries, 198, 254 

indexes, 195, 210 

information road maps, 211 

margin icons, 212 

margin notes, 212 

overuse of, 213 

overviews, 210 

running feet, 212 

running heads, 212 

shading, 213 

structural cues, 209 

table of contents, 195, 209, 254 

titles, 210 

typeface changes, 213 

type size changes, 213 
New components, listing in information plan, 

73 

Nondisclosure agreements, 219 
Nongoals, in information plan, 74 
Notes, indexing, 169 
Noun phrases, as primary index entries, 174 
Nouns 

glossary definitions of, 161 

primary index entries, 174 

secondary index entries, 181 
Number of levels of index entries, 184 
Number of page references for primary index 

entry, 181 

Numbers 

indexing, 180 

style sheet and, 156 
Numerals, indexing, 180 


O 


Objects, screen, online help for, 199 
OLD CD-ROMs 

See CD-ROMs 
Online books 

See also Bookreader 

See also CD-ROMs 

accessibility, 128, 209 

artwork in, 128 
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Online books (cont’d) Online help (cont’d) 


bibliography, 271 DECwindows XUI Help, 199 
checking index, 254 describing in information plan, 75 
chunks of information, 196 first draft review, 128 
color in, 127 freeze date, 89 
confirming delivery, 84 general guidelines, 198 
conventions table, 127 hotspots, 201, 207, 210 
creating, 271 information plan milestones, 87, 88, 89 
cross-references in, 197, 207 information types and, 41 
checklist, 253, 254 links, 201 
hard coding, 127 OpenVMS Help, 202, 203, 271 
DECwrite and, 272 reference pages, 205 
definition of, 194 reviewing, 128 
describing in information plan, 75 second draft review, 128 
design, 127 signoff review, 129 
editorial review, 128 table of contents, 210 
elements, 127 VAX DOCUMENT and, 271 
emphasis in, 127 Online information 
examples, 127 See also Online books 
figures, 127 See also Online help 
front matter, 127, 253 bibliography, 271 
granularity of topics, 127, 128, 196 case study design and, 54, 57 
hotspots, 197, 211, 254 combining methods, 207 
indexes, 127, 128, 185 definition of, 193 
indexing guidelines, 198 describing in information plan, 73, 75 
information types and, 41 editing, 113,128 
pop-up windows, 197 field test milestones, 87, 88 
producing, 271 hypermedia, 206 
quality assurance checklist, 253 information types and, 41 
reviewing, 126, 253 linking, 201, 207 
section titles, 128 reviewing, 126 
submission milestones, 84 Open-ended questions, 225 
table of contents, 127, 254 Open systems, 11, 12 
tables, 127 OpenVMS Help, 202 
testing, 84 bibliography, 271 
testing Bookreader files, 253 creating, 203 
topics, 196 guidelines, 203 
VAX DOCUMENT and, 271 sample help module, 204 
Online examples, describing in information structure of, 203 
plan, 75 OpenVMS online documentation disc, 138 
Online help, 198 Options, indexing, 172, 178 
accessibility, 209 Order numbers 
bibliography, 271 file names and, 77 
context-sensitive help, 199 production and packaging plan, 93 


DECwindows Motif Help, 200 
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Organizational editing, 103, 110 
Outlines 

first drafts and, 101 

in information plan, 75 
Overuse of design navigational cues, 213 
Overviews, 210 


p 


Packaging 
See Production and packaging plans 
Packaging plans 


See Production and packaging plans 
Page counts 

changing attitudes towards, 13 

determining staffing needs and, 68 

in production and packaging plan, 94 
Page numbers 

as index locators, 166 

online book indexes, 185 

with index cross-references, 185 
Page references in index entries, number of, 

181 

Parallelism, glossary entries, 161 
Parameters, indexing, 172, 178 
Part numbers 

file names and, 77 

production and packaging plan, 93 
Part pages, navigational cues and, 210, 211 
Peer reviews, 115 
Performance objectives for usability studies, 

217 

Performance tests, 238, 241 
Phase 0, 20 

information plan milestones, 85 

preliminary information plan and, 64 
Phase l, 20 

final information plan and, 85 

information plan milestones, 85 
Phase 2, 20 

information plan milestones, 85 
Phase 3, 20 

information plan milestones, 87 
Phase 4, 20 

information plan milestones, 90 


Phase Review Process 
closure dates in master information plan, 
83 
information plan milestones and, 84 
information plans and, 61, 64 
stages of, 19 
Physical kits, 95 
Pilots of usability studies, 223 
Planning 
See also Budgeting 
See also Scheduling 


See also Staffing 
contingency plans in information plan, 92 
information plan and, 61 
milestones in information plan, 83 to 90 
submitting to an external organization, 
33 
telephone interviews, 229 
usability studies, 77, 216 to 218 
Plurals, using in index entries, 180 


Points of entry 
See Indexes 
Pop-up windows, 127, 197 
checking online, 254 
Postmortems 
See Post-project review meetings 
Postpartums 
See Post-project review meetings 
Post-project review meetings, 141 to 145 
agenda, 143 
limiting participation in, 143 
moderator responsibilities, 144 
participants, 142 
purpose of, 141, 142 
report, 144 
archiving, 145, 149 
purpose of, 144 
timing of, 141 
writing responsibilities, 141 
Preliminary information plans, 63 
See also Information plans 
information plan milestone, 85 
Phase 0 meeting and, 64 


Index 309 


Prepositional phrases, as secondary index 


entries, 181 


Prepositions, in secondary index entries, 182 
Presentation, method of, editing for, 103 


Pretests of usability studies, 223 
Primary index entries, 166 
adjectives, 174 
adverbs, 174 
capitalization, 180 
compound phrases, 176 
gerunds, 174 
nouns, 174 
selecting, 172 
verb phrases, 175 
Print date milestone 
See Final production 
Printer salts 
See Film master proofs 
Printing, effect on schedule, 66 
Printing services, 139 
Print specifications 
purpose of, 136 
quality assurance checklist, 261 
submitting to production group, 90 
Privileges needed, listing in information 
plan, 83 
Problem reports 
as research source, 30 
project maintenance, 92, 149 
Procedures 
editing, 111 
indexing, 172 
usability studies and, 216 
Process 
bibliography for, 272 
design, 35 
draft, 100 
information creation, 19 
Phase Review, 19 
product development, 19, 99 
review, 100 
Product, defined, 3, 24 
Product components, indexing, 169 
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Product dependencies, in information plan, 
72 
Product description, information plan and, 
72 
Production 
See Final production 


See Graphic designers 


See Production specialists 
Production and packaging plans, 93 

art requirements, 94 

binding methods, 94 

block count, 94 

cover types, 94 

delivery media, 95 

format, 93 

information plans and, 70 

ink colors, 94 

kitting information, 95 

manufacturing group, 93, 95 

manufacturing project numbers, 93 

order numbers in, 93 

page count, 94 

part numbers in, 93 

quality assurance checklist, 252 

separate from information plan, 95 

spines, 94 

submission methods, 93 

tabbed dividers, 94 

tools, 93, 95 

trim size, 94 
Production specialists 

information plan and, 62 

post-project review meeting, 142 

role in user information team, 7 
Productivity metrics, staffing and, 68 
Product management 

as information resource, 31 

as user reviewers, 114 

business plan, 26 

final signoff, 129 

information plan signoff, 70 

marketing requirements document, 26 

product requirements document, 26 

trademark information and, 243 


Product problem reports 
as research source, 30 
project maintenance, 92, 149 
Product prototype, using, 28 
Product requirements document, 26 
Product research 
See also Research 
information needed, 24 
modular design and, 37 
quality assurance checklist, 249 
sources for, 25 
usability studies and, 216 
Product shipment date, 66 
information plan milestone, 90 
master information plan milestone, 83 
Product specifications, 26 
Product team 
attending meetings of, 28 
members of, 10 
Program team 
See Product team 
Project archives 
information plan, 149 
post-project review report, 145, 149 
reproduction package, 149 
source files, 149 
user feedback, 149 
Project closure, 141 
archiving, 149 
client satisfaction surveys, 145 
post-project review, 141 
post-project review report, 144 
Project glossaries 
See also Glossaries 
compared to customer glossaries, 159 
defined, 158 
Project leader, information 
information plan and, 62 
post-project review meeting, 141, 142, 
143 
post-project review report, 144 
responsibilities, 8 
Project leader, technical, and post-project 
review meeting, 142 


Project maintenance 
information plan description, 92 
responding to user feedback, 147 
Project planning documents 
research source, 25 
types of, 26 
Project team 
See Product team 
Proofreading 
final production and, 135 
master copy, 137 
repro proofs, 137 
Proofs 
See Film master proofs 
Proprietary information classification, 
information plans and, 70 
Protocol-aided revision, 238, 241 
Publishing tools, 93 
changing environment, 13 
Punctuation 
editing for, 110, 112 
style sheet and, 156 
Purpose, editing for, 110 


Q 


Qualifiers, indexing, 172, 178 
Quality assurance 


See also Reviews 
See also Usability studies 
See also User feedback 
installation milestones, 87, 90 
review process and, 99 

Quality assurance checklists 
assembly sheets, 262 
audience research, 248 
Bookreader books, 253 
color and screen markup copy, 261 
film master proofs, 263 
information plans, 251 
mechanicals, 260 
print specifications, 261 
production and packaging plans, 252 
product research, 249 


Index 311 


Quality assurance checklists (cont’d) 


questionnaires, 256 

reproduction packages, 259 

repro proofs, 259 

telephone interviews, 258 
Questionnaires 

as research tool, 30 

benefits, 239 

close-ended questions, 225 

delivery methods, 225 

field test, 125 

for project evaluation, 145 to 147 

guidelines for, 226 

open-ended questions, 225 

quality assurance checklist, 256 

screening participants with, 221 

usability studies, 224 to 227 


R 


Read and locate tests, 233 to 236 
analyzing results, 235 
benefits, 240 
conducting, 234 
designing, 233 
Reader comment cards, 30, 92 
archiving, 149 
purpose and value of, 147 
sample, 148 
Readers for formal document inspections, 
118 
Readiness reviews, master information plan 
milestones, 83 
Recorders for formal document inspections, 
118 
Recto/verso layout sheets, 137 
Redundancy 
controlling, 15 
editing for, 111, 112 
Reference information, 38 
hardware information and, 39 
information architecture and, 41 
software information and, 48 
Reference pages, 205 
case study and, 52 
describing in information plan, 75 
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Reference pages (cont'd) 


elements, 206 
sections, 205 
Related terms in glossary, 164 
Related topics in index, 167, 185 
Repro 
See Repro proofs 
Reproduction packages 
archiving, 149 
contents of, 136 
delivery to manufacturing, 90 
preparing, 137 
quality assurance checklist, 259 
reviewing, 137 
Repro proofs 
defined, 135 
quality assurance checklist, 259 
reviewing, 137 
Research . 
See also Usability studies 
audience, 22, 248 
competitive literature, 31 
corporate libraries, 31 
courses, 31 
customer questionnaires, 30 
customer visits, 29 
gathering information, 25 
information team as resource, 29 
internal users as resource, 29 
product, 24, 249 
product manager as resource, 31 
product prototype as resource, 28 
product team meetings, 28 
project planning documents, 25 
service groups as resource, 30 
sources for, 25, 29 
support groups as resource, 30 
technical team as resource, 27, 28 
trade publications, 31 
user feedback tools, 30 
user groups as resource, 30 


Reuse, and modular information, 14, 15 


Review comments 
gathering at review meeting, 116 
incorporating, 122 


Review comments (cont’d) 


incorporating from field test reviews, 126 


late, 123 

responding to, 122 
Reviewers 

checking list of, 105 

editorial, 109 

information plan, 70, 79 

signoff, 129 

technical, 109 

types of, 109 

user, 114 
Review meetings, 116 

process, 116 

review cover memo for, 116 

scheduling in information plan, 116 
Review process 


See also Reviewers 

See also Reviews 

editorial review elements, 110 

editorial review responsibilities, 110 

field test milestones, 86, 87, 88 

field test reviews, 123 

final signoff milestones, 89 

first draft edit, 110 

first draft review milestone, 85 

glossaries, 160 

incorporating review comments, 122 

indexes, 88, 191 

information plans, 63 

installation guide draft review, 86 

late review comments, 123 

online books, 126 

online help, 128 

online information, 126 

online information milestones, 87, 88 

project leader role, 9 

second draft edit, 110 

second draft review milestones, 87 

signoff draft edit, 110 

steps in, 100 

submission to quality assurance group, 
87, 90 

testing online files, 84 

types of reviewers, 109 


Review process (cont'd) 
usability studies, 215 
user reviewers, 114 
Reviews 
document inspection, 117, 121 
- editorial review elements, 110 
field test reviews, 99, 123 
formal reviews, 99, 104 
cover letter, 105 
distributing review copies, 108 
list of reviewers, 105 
number of, 104 
preparing for, 104 
preparing review drafts, 107 
review package, 108 
scheduling, 107 
types of editing, 110 
update packages, 108 
informal reviews, 99 
editing, 103 
scheduling, 103 
working with technical experts, 103 
internal reviews, 103 
document inspections, 117 
peer reviews, 115 
review meetings, 116 
online books, 126 
online information, 126 
peer reviews, 115 
review meetings, 116 
types of, 99 
types of reviewers, 109 
Reviews, post-project 
See Post-project review meetings 
Revised components, listing in information 
plan, 73 
Risks, information plan description, 91, 92 
Routines, indexing, 173, 178 
Running feet, as navigational cues, 212 
Running heads, as navigational cues, 212 
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Salts 


See Film master proofs 


Sample layout sheets, 137 
Scheduling, 65, 66 


base levels and, 65 

changes in project dates, 66 

counting backwards, 66 

critical project dates, 65 

evaluating at post-project review meeting, 
143 

field tests and, 65 

formal reviews, 107 

illness and, 67 

indexing, 167 

informal reviews and, 103 

manufacturing submission and, 65 

milestones in information plan, 83 to 90 

project leader role, 9 

shipment date and, 66 

slips, 92 

tasks to consider, 66 

telephone interviews, 228, 229 

training and, 67 

usability sessions, 223 

vacations and, 67 


Screens 


See Color and screen markup copy 


Secondary index entries, 166 


adjectives, 181 

articles in, 182 
capitalization, 183 
conjunctions in, 182 
consolidating, 184 
creating, 181 

nouns, 181 

prepositions in, 181, 182 
selecting, 181 

verbs, 181 


Second color markup 


See Color and screen markup copy 


Second drafts 


editing, 110 
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Second drafts (cont'd) 

online help, 128 

review, 104 

review milestones in information plan, 87 
Section titles 

indexing, 173 

navigational cues, 210 

online books, 128 
See also cross-references 

in glossary, 164 

in index, 167, 185, 188 
See cross-references 

in glossary, 164 

in index, 167, 185, 186 
Semicolons, in glossary definitions, 163 
Service groups 

as information resource, 30 

as user reviewers, 114 
Service marks 

See Trademarks 
Shading, as a navigational cue, 213 


Shipment date 


See Product shipment date 
Signoff 
changes to information plan after, 64 
editing, 110 
final, sample form, 130 
final component review, 89 
final production, 137 
identifying reviewers in information plan, 
79 
information plan, 63, 64, 85 
information set, 129 
online help review, 129 
review, 104 
Signoff reviewers 
information plan, 70 
information set, 129 
SIGs (Special Interest Groups), as research 
information source, 30 
Singular nouns, using in index entries, 180 
Slash characters, in index entries, 178 
Small capital letters, for emphasis, 213 


Software, identifying in information plan, 
72, 83 
Software information 
information architecture example, 48 
organizing by information type, 48 
Software Performance Reports 


See SPRs 
Source files 
archiving at end of project, 149 
file naming conventions, 76, 77 
file types in information plan, 73 
transmission to internationalization 
group, 84 
Special Interest Groups (SIGs), as research 
information source, 30 
Spelling 
editing for, 110, 112 
style sheet and, 156 
Spelling checker tools, using, 107 
Spines, in production and packaging plans, 


SPRs, 30, 92, 149 
Staffing 
estimated costs in information plan, 82 
information plan listing, 79 
planning, 67 
productivity metrics and, 68 
ratios, 67 
Standards 
bibliography, 272 
case study and, 52 
complying with, 12, 33 
editing and, 111 
effect on terminology, 156 
formal, complying with, 11 
for terminology, 268 
indexing, 173 
ISO, 92 
listing in information plan, 92 
waivers for, 92 
Status of components, listing in information 
plan, 73 
Structural navigational cues, 209 
Structured interviews, 227 


Style 
See also Format 
See also Style sheets 


See also Word lists 
bibliography, 265, 266 
editing for, 112 
house style, 156 
types of guidelines, 156 
Style checking tools, using, 107 
Style sheets 
See also Authority lists 
contents, 156 
editor creating, 156 
production group and, 157 
sample, 157 
writers and, 157 
Subentries, index 
See Secondary index entries 
Submission methods, in production and 
packaging plan, 93 
Substantive editing, 7, 110 
Summary tests, 232 to 233 
benefits, 240 
process, 233 
Support groups 
as information resource, 30 
as user reviewers, 114 
Surveys, client satisfaction, 145 to 147 
See also Questionnaires 
advantages, 145 
disadvantages, 145 
improving results, 146 


sample, 145 
Switches, indexing, 172,178 
Symbols 


indexing, 178, 180 

style sheet and, 156 
Synonyms 

in glossaries, 162, 164 

in indexes, 167,176,177 


System accounts, listing in information plan, 


83 
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T 


Tabbed dividers 
in production and packaging plan, 94 
navigational cues and, 210, 211 
Table of contents 
DECwindows Motif Help System and, 
210 
editing, 112 
information plan and, 70 
navigational cue, 209 
needed for Bookreader, 195 
online books and, 127, 128, 254 
Tables 
checking online, 254 
DECwindows Motif Help and, 201 
editing, 112 
indexing, 173 
in pop-up windows, 197 
online books, 127 
Task-oriented information, 38 
hardware information and, 39 
information architecture and, 41 
software information and, 48 
Tasks, indexing, 168, 173, 175 
Technical design documents, 26 
Technical development plan, 26 
Technical experts 
as reviewers, 109 
attending meetings of, 28 
design documents, 26 
final signoff and, 129 
informal reviews and, 103 
information plan signoff and, 70 
post-project review meeting, 142 
product specifications, 26 
project plans, 26 
working with, 27, 102 
Technical project leader 


See Project leader, technical 
Technical reviewers, 109 

in information plan, 79 

responsibilities, 109 

review meetings and, 116 
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Telephone interviews, 227 to 230 
advance notice for, 228, 229 
benefits, 239 
field test users, 125 
guidelines, 228 
quality assurance checklist, 258 
training interviewers, 229 

Templates, internationalization and, 77 

Terminology 
abstract, 155 
appropriateness, 153 
catch-all phrases, 155 
clarity of definitions, 154 
concrete, 155 
consistency, 153, 154 
culture-specific, 155 
general guidelines, 154 
glossaries, 158 
house style, 156 
jargon, 155 
standards for, 268 
style guidelines, 156 
style sheets, 156 
translation and, 155 
word lists, 158 

Terms, indexing, 169, 173,177 

Tertiary index entries, 184 

Testing constraints, 217 

Testing methods, 217 

Testing plans 
defining, 217 
information plans and, 217 
sample, 217 

Test participants 
advance notice for contextual inquiry, 

237 


advance notice for telephone interviews, 


228, 229 
customers as, 219 
employees as, 219 
following up with, 223 
reminders for, 223 
requesting participation, 219 
scheduling usability sessions, 223 
screening, 221 


Test participants (cont'd) 
working with, 218 to 223 
Third-party trademarks, 244 
Title pages, for information plans, 70 
Titles 
editing, 112 
indexing, 173 
listing in information plan, 73 
master indexes and, 189 
navigational cues, 210 
Tone, editing for, 110, 112 
Tools 
file maintenance, 82 
internationalization and, 77, 82 
marking draft changes, 107 
production and packaging plans and, 95 
publishing, 13, 93 
spelling and style checkers, 107 
Top-down design, 41 
Topic/audience matrixes 
defined, 45 
developing, 45, 46, 47 
Topic headings, index 
See Index entries 
Topic modules 
See Modular information 
See Modules 
Topic overviews, 210 
Topics 
See also Modules 
analyzing for index, 171,177 
granularity, 196 
linking, 201, 207 
online information and, 196 
titles, as navigational cues, 210 
Trademarks 
editing for proper use, 112 
information sources, 243 
needed information, 243 
registered, 243 
style sheet and, 156 
third-party, 244 
Trade publications, as research tool, 31 
Training 
courses as research tool, 31 


Training (cont’d) 
field test, 124 
modular information methods, 267 
requirements in information plan, 83 
scheduling and, 67 
telephone interviews and, 229 
usability, 270 
Training group 
as part of product team, 10 
as user reviewers, 114 
information plan review and, 79 
Translation 
See Internationalization 
Translation coordinators, 9 
post-project review meeting and, 142 
responsibilities, 9, 78, 84 
Trim sizes, in production and packaging 
plan, 94 
Tutorials, 38 
Typefaces, as navigational cues, 213 
Type sizes, as navigational cues, 213 
Typographic conventions 
navigational cues, 213 
style sheet and, 156 


U 


ULTRIX online documentation disc, 138 
UNIX reference pages 


See Reference pages 
Updates 
listing in information plan, 73 
reviews for, 108 
Usability, editing for, 112,113 
Usability edits, 230 to 232 
benefits, 240 
formal, 230, 231 
informal, 231 
types of, 230 
Usability studies 
bibliography, 269 
conditions, 217 
constraints, 217 
contextual inquiry, 236 to 238, 240 
creating testing plans, 217 
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Customer Publications Consulting: 
Customized Information Solutions 


Take advantage of Digital’s product and technology experience to develop 
customized publications solutions — including document management, 

online documentation, document conversion services, integrated help, 
electronic document distribution, CALS, CDA, content-based retrieval services, 
multimedia, internationalization, imaging, and training. 


How You Benefit 


Digital can recommend and deliver high-quality, cost-effective solutions you 
need to: 


¢ Cut development costs 

e Reduce time to market 

e Streamline the documentation process 

e Take advantage of efficient technology and processes 

e Increase your return on investment 

e Improve the quality and effectiveness of your information products 


Publications Services Portfolio 


Digital offers a variety of publications services including business needs 
analysis, online documentation integration (including hyperinformation 
and multimedia), documentation planning, knowledge seminars, document 
conversion, and customization of Document Type Definitions (DTDs). . 


For your customized information solution, 
call Customer Publications Consulting 
at (603) 884-2488 or (603)884-1535. 


Software Development: Documentation 


The Digital Technical Documentation Handbook describes the 
process of developing technical user information at Digital Equipment 
Corporation. It discusses techniques for making user information more 
effective, provides quality assurance checklists, and contains a glossary 
and a bibliography of resources for technical communicators. In addition 
to the actual development of user information, the book covers the draft 
and review process, the production and distribution of printed and elec- 
tronic media, archiving, indexing, testing for usability, and many other 
topics of interest to anyone concerned with developing and producing 
technical documentation. 


Also available from Digital Press 


The Digital Style Guide 
Schultz/Darrow/Kavanagh/ Morse 
1993, Softbound, EY-J883E—DP 


The Art of Technical Documentation 
Katherine Haramundanis 
1992, Softbound, EY-H892E-DP 


Developing International User Information 
Jones/Kennelly/Mueller/Sweezey/Thomas/Velez 
1992, Softbound, EY-H894E-—DP 


Digital Guide to Developing International Software 
1992, Softbound, EY-F577E—DP 


The Digital Guide to Software Development 
1989, Softbound, EY-C178E—DP 
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Digital Press 
Digital Equipment Corporation Order Number EY-J885E—DP 
One Burlington Woods Drive DP ISBN 1-55558-103-X 


Burlington, Massachusetts 01803 PH ISBN 0-13-115932-1 


